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Section 1 
LEARNING GUIDE 



INTRODUCTION 

This Learning Guide gives an overview of features and functions of the Tektronix Assembler, 
Linker, and Library Generator. It also presents a simple demonstration for hands-on 
experience. The Learning Guide is divided into the following topics: 

• About This Manual. Explains how to use this manual with your assembler. 

• System Overview. Describes the functions of the assembler, linker, and library 
generator. Shows how these system programs interact with each other and with other 
programs in the operating system. 

• Features of the Assembler, Linker, and Library Generator. Lists features of these 
programs that make them especially useful and powerful. 

• Demonstration Run. Shows how to enter and assemble a simple program and 
subroutine, and how to prepare the resulting object modules for loading into memory. 

• For Continued Learning. Helps you decide where to go next in this manual to 
accomplish your own tasks. 



ABOUT THIS MANUAL 

The Tektronix Assembler, Linker, and Library Generator are fundamentally the same for 
every microprocessor supported. Each assembler recognizes a different instruction set, 
different registers, and different addressing modes; however, you may use the same 
assemb'er directives, operand expressions, symbols, constants, and advanced programming 
features with any assembler provided. 

The Assembler Specifics section of this manual gives the instruction set and other processor- 
dependent information for your microprocessor. The information in the rest of this manual 
applies to all microprocessors supported. Once you have used one version of the Tektronix 
Assembler, Linker, and Library Generator, you can program for any microprocessor 
supported, as soon as you learn that microprocessor's instruction set. 

The Demonstration Run in this Learning Guide demonstrates the 8080A assembler. 
Demonstration Runs for microprocessors other than the 8080A are found in the Assembler 
Specifics section. 

Programming examples in the Learning Guide and Assembler Specifics sections are specific 
to each microprocessor. AM examples in other sections of this manual are completely 
processor-independent. Some examples use 8080A instructions, but similar instructions for 
any other microprocessor may be substituted without changing the validity of any example. 
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SYSTEM OVERVIEW 

Figure 1-1 shows how an executable program is produced from assembly language source 
files. 

An assembly language source program is created in one of three ways: 

1. It may be written by a programmer. 

2. It may be produced by a compiler, such as MDL//U. 

3. It may be translated from a similar program written for the manufacturer's assembler. 
For this purpose, Tektronix provides converter programs for some microprocessors. 
See the Assembler Specifics section of this manual. 

The assembler translates assembly language statements (source code) into machine 
instructions (object code) and stores the resulting object module on a disc file called an 
object file. 

The linker collects object modules from specified files and determines where in memory each 
section of object code will reside. The load file produced by the linker contains the 
executable program, which you may copy into memory using the TEKDOS LOAD command. 
(Under certain conditions you may load object modules without linking them. See the Linker 
section.) 

Commonly used subroutines can be developed and assembled separately. Their object code 
can then be stored with other useful object modules in a library file. When you include calls 
to library routines in your source program, the linker inserts the necessary object modules 
into the load file. The library generator creates and modifies library files. 
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Fig. 1-1. Assembler programming process. 



The assembler translates assembly language programs (source code) into relocatable machine 
language (object code). Commonly used object modules may be stored together in library files created 
by the library generator. The linker combines object modules from specified object files and library files 
into a load file of executable object code. The TEKDOS command LOAD copies object code from load 
files into program memory. 
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ASSEMBLER FEATURES 

Here are some important features of the assembler: 

• Macros provide a convenient and powerful means for inserting and modifying 
frequently used segments of source code. 

• Conditional assembly allows a sequence of source code to produce object code that 
varies according to specified conditions. This feature reinforces the assembler's macro 
capabilities. 

• Linker-related assembler directives allow you to specify in your source code how the 
object code will be arranged in memory. 

• Operand expressions may contain bit and string manipulations and special assembler 
functions as well as the standard arithmetic operations. 

• Data constants may be entered as numbers in binary, octal, decimal, or hexadecimal 
notation, or as strings of ASCII characters enclosed in quotes. 

• Each error message contains a brief description of the error, plus an error number that 
helps you refer to this manual for more information. You may also write your own error 
messages for use in conditional assembly. 

• The assembler listing shows your source code, and the object code, error messages, 
and symbol table produced by the assembler. Listing directives allow you to select 
which segments of code or types of code are listed. 
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UNKER FEATURES 

Here are some important features of the linker: 

• You may link object modules from any number of object files or library files. 

• You may define or change any of the following attributes at link time: 

— the relocation type of a section of object code; 

— the exact or approximate location of a section in memory; 

— the values assigned to global symbols; 

— the address of the first instruction to be executed. 

• You may specify simple linking operations with a single LINK command line. Special or 
complex operations can be specified with linker commands entered from the system 
terminal or from a command file. 

• Each error message contains a brief description of the error and gives the severity of the 
error (WARNING, ERROR, or FATAL ERROR). When you enter an illegal command, the 
linker indicates which word or parameter is erroneous. 

• The linker listing gives a detailed account of linker activity, showing the commands 
executed, local and global symbols, memory maps, and statistics. 



LIBRARY GENERATOR FEATURES 

Here are some important features of the library generator: 

• You may create libraries of up to 100 modules from any number of object files. 

• You may modify libraries by inserting, deleting, or replacing object modules. 

• You may extract individual object modules onto disc files. 

• You may enter library generator commands from the system terminal or from a 
command file. 

• Each error message contains a brief description of the error. When you enter an illegal 
command, the library generator indicates which word or parameter is erroneous. 

• The library generator listing shows the commands executed, global symbols, and a 
summary of library generator activity. 
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DEMONSTRATION RUN 
Introduction 

This Demonstration Run shows you how to enter, modify, assemble, link, and load a simple 
program and subroutine. This demonstration uses the 8080A assembler. If you have an 
assembler other than the 8080A, refer to the Assembler Specifics section of this manual for 
a Demonstration Run that is parallel to this one. 

The purpose of this demonstration is to give you the basic information and experience you 
will need to begin using the assembler, linker, and library generator. 

For your convenience, the sample program and subroutine are short and trivial. Only a few 
features of the assembler and linker are demonstrated, and the library generator is not 
discussed. 

This Demonstration Run uses the following conventions: 

1 . Underlined — Underlined characters in a command line must be entered from your 
system terminal. Those characters not underlined are system output. 

2. <CR> — Each command line ends with a carriage return. When a carriage return is to 
be entered, the symbol <CR> is used. 

Preparation 

To do this Demonstration Run you should have a basic understanding of the 8002A 
/^Processor Lab and the TEKDOS Editor. If you need to review how the 8002A and its editor 
work, refer to the Learning Guide in the 8002A System Users Manual. 

You will need about 60 minutes to complete this Demonstration Run. 

Start up your 8002A system. Make sure your system disc has a write-enable tab and is 
inserted into disc drive 0. 

Examine your disc directory to make sure you have at least 10 blocks available for the files 
created during this demonstration: 

> LDIR <CR> 



FILE NAME BLKS 

TEKDOS 16 

170 

COPYSYS 1 

NEWDISC 1 

TOTAL FILES 4 

TOTAL BLOCKS USED 188 

BLOCKS AVAILABLE 106 -^ Must be at least 1 blocks. 

TOTAL BAD BLOCKS 

> 
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If there are not at least 10 blocks available on your system disc, you must make some room 
by copying some of your non-system files to another disc: 

1. Insert another write-enabled disc into disc drive 1. 

2. Repeat the following three commands until you have at least 10 blocks available. 

> COPY filename/0 filename/1 <CR> 

> DELETE filename/0 <CR> 

> LDIR <CR> 

(filename represents any non-system file.) 



Examine the Sample Subroutine and Main Program 

Figure 1-2 lists the subroutine and program you will enter, assemble, link, and load in this 
Demonstration Run. 

The subroutine performs a trivial task: it outputs the ASCII character stored in the 
accumulator to the port whose number is specified by the symbol PORTN. 

The main program stores a character in the accumulator, calls the subroutine to output the 
character, and then halts. 

You can think of the subroutine as a carefully prepared component of a major programming 
project. The main program can be viewed as a quickly written test for the subroutine. 
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Subroutine OUTSUB: 

TITLE "SAMPLE SUBROUTINE" 

NAME SUBSMOD 

GLOBAL PORTN, OUTSUB 

SECTION SUBS1 
; SUBROUTINE OUTSUB -- OUTPUTS A CHARACTER. 
OUTSUB OUT PORTN ; OUTSUB STARTS HERE. 

RET ; RETURN TO PROGRAM. 

END 



Main Program: 





GLOBAL 


PORTN, OUTSUB 


PORTN 


EQU 


15 


PORT = 15 


START 


MVI 


A II ? » 

ft. , 


CHARACTER = "?" 




CALL 


OUTSUB 


SEND "?" TO PORT 15 




HLT 




... AND STOP. 




END 


START 
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Fig. 1-2. Source code for the sample subroutine and program. 

Subroutine OUTSUB outputs a single ASCII character to port number PORTN. The main program 
specifies a port number and a character and calls OUTSUB to output the character. The subroutine and 
main program are discussed in more detail later in this section. 

Assembly Language Statements 

An assembler source module is made up of assembly language statements. There are three 
types of assembly statements: 

• An assembly language instruction is translated by the assembler into an 8080A 
machine instruction. 

• An assembler directive indicates a special action to be taken by the assembler . 
Assembler directives define data items, constants, and variables; provide information to 
the linker; control macros and conditional assembly; and specify options for the 
assembler and linker listings. 

• A macro invocation is replaced by statements of the macro it invokes. (Macro 
invocations are not discussed in this demonstration.) 

Each assembly language statement has four fields. Each field may vary in width, and certain 
fields may be blank. However, the fields always occur in the following order: 

1 . The label field. The label field always begins in column 1 of the statement. The label 
allows the statement to be referenced by other statements. The label usually 
represents the address of the instruction or data item represented by the statement. 

2. The operation field. The word in the operation field indicates the type of action to be 
taken by the assembler. The word may be an assembler directive, an 8080A 
mnemonic, or the name of a macro. If the word is an 8080A mnemonic, the assembler 
translates the statement into a machine instruction. 



1-8 



Learning Guide— 8002A: Assembler Users Manual Demonstration: Examine Program 



3. The operand Tieia. i ne operand neia completes tne assemDiy language statement. 
Most assembler directives and 8080A instructions contain one or more operand 
expressions. The type and number of operands depend on the operation. 

4. The comment field. Comments are used for program documentation only; they are 
ignored by the assembler. A semicolon (;) indicates that the remainder of the line is a 
comment. A comment may follow the operand field, or may begin with a semicolon in 
column 1 and take up an entire source line. 



Explanation of the Subroutine Source Code 

The following text explains each statement in the sample subroutine (shown in Fig. 1 -2). The 
two statements preceding the END statement are 8080A instructions. The rest of the 
statements are assembler directives. 

TITLE "SAMPLE SUBROUTINE" 

The phrase "SAMPLE SUBROUTINE" will appear in the heading on each page of the 
assembler source listing. 

NAME SUBSMOD 

When the subroutine is assembled, the resulting object module will be named "SUBSMOD". 

GLOBAL PORTN,OUTSUB 
PORTN and OUTSUB are declared as global symbols, since each symbol is given a value in 
one module and referred to in another module. For example, OUTSUB is defined in the 
subroutine and referred to in the main program. PORTN is called an unbound global because 
it is not defined anywhere in this module. OUTSUB is a bound global. 

SECTION SUBS1 
Each object module is composed of one or more sections. The linker treats each section as a 
separate unit: sections from the same module may be placed in different ends of memory. 
The one section in object module SUBSMOD will be called SUBS1 . (If you were to add other 
sections to this source module, they might be called SUBS2, SUBS3, and so on.) 

The assembler directives SECTION, COMMON, and RESERVE each declare a different type of 
section, and may also specify restrictions on the relocatability of the section. When no 
restriction is specified, the section is byte-relocatable; that is, the section may begin at any 
byte in memory. The Linker section of this manual contains an explanation of the five 
attributes of a section: name, section type, relocation type, size, and memory location. 

; SUBROUTINE OUTSUB -- OUTPUTS A CHARACTER. 
This is a comment. 
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OUTSUB OUT PORTN ; OUTSUB STARTS HERE. 

This 8080A instruction outputs the contents of the accumulator to port number PORTN. The 
symbol OUTSUB becomes defined as the address of this instruction, which is the first 
instruction in the subroutine. A program that contains the instruction CALL OUTSUB can 
execute this subroutine. 

RET ; RETURN TO PROGRAM. 

This 8080A instruction returns control to the calling program. 

END 
This assembler directive marks the end of the source module. 



Explanation of the Main Program Source Code 

The following text explains each statement in the sample main program (shown in Fig. 1-2). 
The program contains three assembler directives (GLOBAL, EQU, and END) and three 8080A 
instructions (MVI, CALL, and HLT). 

GLOBAL PORTN, OUTSUB 
As in the subroutine, PORTN and OUTSUB are global symbols. However, in this module 
PORTN is a bound (defined) global while OUTSUB is an unbound (undefined) global. The 
GLOBAL statements allow the two modules to share the number of the port and the address 
of the subroutine. 

PORTN EQU 15 ; PORT = 15 

This assembler directive assigns the value 15 to the symbol PORTN. "PORTN" becomes 
synonymous with the constant "15". 

START MVI A,"?" ; CHARACTER = "?" 

This 8080A instruction stores the hexadecimal value 3F (the ASCII code for question mark) in 
the accumulator. This statement is given a label, "START", so the END statement may refer 
to it. 

CALL OUTSUB ; SEND "?" TO PORT 15 ... 
This 8080A instruction transfers control to the instruction labeled OUTSUB in the subroutine 
module. The subroutine sends the question mark to port 15. 

HLT ; . . . AND STOP. 

Control returns from the subroutine to this 8080A instruction. The HLT instruction halts 
program execution. 

END START 

This assembler directive terminates the source module and indicates that program execution 
should begin with the instruction labeled "START". START is called the transfer address. 
The transfer address is passed through the assembler and linker to the TEKDOS commands 
LOAD and GO. 
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Demonstration: Naming Files 



i\iotice tnat tnis program source module does not contain a TITLE, NAME, or SECTION 
directive. The following default conditions result: 

• No special title will appear in the page heading of the source listing. 

• The object module will be called *NONAME*. 

• The one section in *NONAME* will be given a default name, section type, and 
relocation type. 

Naming Files 

This Demonstration Run produces several files. To give each file a name that reflects its 
contents and importance, we will use the file naming standards described in the File 
Management section of the 8002A System Users Manual: 

• The last character of the file name is a letter that represents the type of file. 

• The next-to-last character is either a percent sign (%) or a semicolon {;). The percent 
sign signifies a file that cannot be readily replaced. The semicolon signifies a temporary 
or readily replaced file. 

• The first part of the file name is a descriptive name. 
The following files will be produced: 



File Name 


Explanation 


How Created 


DEMSUB%S 


DEMonstration SUBroutine Source file 


by you 


DEMSUB;0 


DEMonstration SUBroutine Object file 


by assembler 


DEMSUB;A 


DEMonstration SUBroutine Assembler listing 


by assembler 


DEMPRO%S 


DEMonstration PROgram Source file 


by you 


DEMPRO;0 


DEMonstration PROgram Object file 


by assembler 


DEMPRO;A 


DEMonstration PROgram Assembler listing 


by assembler 


DEMPRO;L 


DEMonstration PROgram Load file 


by linker 


DEMPRO;K 


DEMonstration PROgram linKer listing 


by linker 



Create the Subroutine Source File 

The TEKDOS Editor helps create and modify source files. The Editor Dictionary section of the 
8002A System Users Manual contains a complete explanation of the editor. 

How to Correct Typing Mistakes in the Editor 

To delete the last character typed, use the BACKSPACE, RUBOUT, or DELETE key: 

• The BACKSPACE key on a CRT terminal cancels the character and backs the cursor over 
it. 

• The RUBOUT key on a CRT terminal cancels the character and echoes the cancelled 
character on the terminal. 

• The DELETE key on a hard-copy terminal cancels the character and echoes the 
cancelled character on the terminal. 

To delete the entire line being typed: 

• Press the ESC (escape) key once. You may then reenter the line. 



@ 
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Start Editing 

The EDIT command invokes the TEKDOS Editor. The file name in the EDIT command 
indicates the file to be edited. Enter the following line to begin the editing session that 
creates DEMSUB%S, the subroutine source file: 

> EDIT DEMSUBftS <CR> 

** EDIT VER x.x ** 

**NEW FILE** 
* 

The asterisk (*) is the editor prompt character. When you see the asterisk, you may enter the 
next editor command. 

An assembly language program is easier to read if the statement fields are aligned as in Fig. 
1-2. The editor has tab stops at columns 8, 16, 24, 32, 40, 48, 56, and 64, which are 
convenient for aligning assembly language text. For example, in Fig. 1 -2, the operation field 
begins in column 8, the operand field begins in column 16, and the comment field begins in 
column 24. 

Enter the following command to declare the dollar sign as the editor tab character: 
* TAB $ <CR> 

The editor will interpret every dollar sign you enter as a skip to the next tab stop. 

Enter input mode and type in the subroutine. Be sure to misspell "GLOBAL" in the third line 
of text. This deliberate typing error will be used to illustrate features of the assembler and 
editor. 

*INPUT <CR> 

INPUT: 

$TITLE$"SAMPLE SUBROUTINE" <CR> 

$name$subsmod <cr> 

sgloablsportn . outsub <cr> 

$secti0n$subs1 <cr> 

; Subroutine outsub — outputs a character. <cr> 

0utsub$0ut$p0rtn$; outsub starts here. <cr> 

$ret$$; return to program. <cr> 

$END <CR> 

<CR> 

* 

When you enter the carriage return on the empty line, input mode is terminated and the 
editor prompt (*) appears. 
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The text you entered is stored in the editor workspace. Each dollar sign you entered has been 
replaced by spaces up to the next tab stop. To display the workspace contents from beginning 
to end, enter the following command: 

*T YPE B-E <CR> 

TITLE "SAMPLE SUBROUTINE" 
NAME SUBSMOD 
GLOABL PORTN,OUTSUB 
SECTION SUBS1 

nnnn/MtfnTitp rtii'T»ntin AllTnilTO A PUB n*PTrn 

; ounnuuiiNC uuioud — uuiruio a onnnauicn. 
OUTSUB OUT PORTN ; OUTSUB STARTS HERE. 

RET ; RETURN TO PROGRAM. 

END 
* 

Now enter the FILE command to copy the text in the workspace out to the new source file 
and end the editing session: 

* FILE <CR> 
*D0~S* EOJ 

> 

The TEKDOS prompt (>) indicates that you are out of the editor and may enter another 
TEKDOS command. 



Assemble the Subroutine and Examine Any Errors 

The TEKDOS command ASM invokes the assembler and specifies the source file{s) to be 
assembled and the object and listing files to be produced. The ASM command has the 
following format: 
ASM,objfile,lisfile,soufile [,soufile]... 

objfile — name of object file to be produced 
lisfile — name of listing file to be produced 
soufile — name(s) of source file(s) to be assembled 

To scan source file DEMSUB%S for errors, enter the following command: 

> ASM, , ,DEMSUB$S <CR> 

Omitting the names of the object and listing files has two advantages: 

1 . The assembler runs faster because it produces no object code or listing. 

2. The ASM command line is shorter. 

You may want to omit these files from your ASM command line whenever you suspect that 
your source code contains errors. 
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The assembler responds as follows on your system terminal: 

Tektronix 8080/8085 ASM Vx.x 

**** pass 2 

00003 0000 000000 GLOABL PORTN, OUTSUB 

***** ERROR 039: Invalid operation code 

00006 0000 D300 OUTSUB OUT P0RTN ; 0UTSUB STARTS HERE. 

***** ERROR 074: Undefined symbol 

8 Source Lines 8 Assembled Lines 47718 Bytes available 

2 ERRORS 2 UNDEFINED SYMBOLS 

*ASM* EOJ 

> 
The assembler's response can be interpreted as follows: 

Tektronix 8080/8085 ASM Vx.x 
The assembler announces itself as it begins executing. The assembler reads through your 
source file twice. The first time through (Pass 1 ), the assembler makes a list of symbols that 
appear in the source code and tries to assign an address or other value to each symbol. 

**** Pass 2 
The assembler begins its second pass through your source file. During Pass 2, the assembler 
produces the object and listing files and displays error messages and statistics. 

00003 0000 000000 GLOABL PORTN, OUTSUB 

***** ERROR 039: Invalid operation code 

The assembler cannot translate the above statement because "GLOABL" is not an 8080A 
mnemonic, an assembler directive word, or the name of a macro. The erroneous source line 
and the error message would appear in the listing (if any) just as they appear on the system 
terminal. The three numbers to the left of the statement will be explained when you examine 
an assembler listing later in this demonstration run. 

00006 0000 D300 OUTSUB OUT PORTN ; OUTSUB STARTS HERE. 

***** ERROR 074: Undefined symbol 
Because the assembler did hot understand the GLOBAL statement, it does not know that 
PORTN is a global symbol. The assembler expects PORTN to be defined in this module. 

8 Source Lines 8 Assembled Lines 47718 Bytes available 
2 ERRORS 2 UNDEFINED SYMBOLS 

These lines summarize the assembler's activities. There are eight lines of code in your 
source file. The number of assembled lines differs from the number of source lines only in 
programs that contain macros or conditional assembly. 

The "Bytes available" message indicates the amount of Program Memory not used by the 
assembler. If the "Bytes available" figure is ever less than 1000 or so, you may need to divide 
your source module into smaller modules before you add any more statements. 

The two errors, already discussed, produced the two undefined symbols GLOABL and 
PORTN. 
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Correct the Error in the Subroutine Source Code 

Both errors detected by the assembler arose from the mlssneiiinn of "GLOBAL" in line 3 of 
the source file,- DEMSUB%S, Invoke the editor so that you may correct the misspelling: 

> EDIT DEMSUB%S <CR> 

** EDIT VER x.x ** 
* 

The editor command GET brings text into the workspace from the file being edited. Specify a 
large number of lines (99) to assure that the entire file is brought into the workspace: 

*GET 99 <CR> 

The message **EOF** indicates that the end of the input file has been reached. 

Enter the following command line. The BEGIN command moves the workspace pointer to line 
1 . Starting at that line, the FIND command searches for the character string "GLO" and 
moves the pointer to the first line that contains the string. 

* BEGIN. :FIND /GLO/ <CR> 

GLOABL PORTN , OUTSUB 

Now the workspace pointer is at the line you want to modify. Use the SUBSTITUTE command 
to reverse the letters "A" and "B" in "GLOABL": 

* SUB /AB/BA/ <CR> 

GLOBAL PORTN, OUTSUB 

The modified line is displayed. 

As before, the FILE command copies the edited source code to the source file and closes the 
editing session: 

*FILE <CR> 
*TE~OT** 

*DOS* EOJ 



Re-Assemble the Subroutine 

Enter the following command to create an object file (DEMSUB;0) and an assembler listing 
file (DEMSUB;A) from the subroutine source file: 

> ASM DEMSUB;0 DEMSUB;A DEMSUB%S <CR> 

Tektronix 8080/8085 ASM Vx.x 
**** Pass 2 

8 Source Lines 8 Assembled Lines 47710 Bytes available 

>>> No assembly errors detected <<< 
*ASM* EOJ 



This time the assembler finds no errors. 
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Examine the Subroutine Listing 

In order to examine the assembler listing stored on file DEMSUB;A, copy the file to your line 
printer: 

> COPY DEMSUB;A LPT1 <CR> 

If you have no line printer, enter the following command to list the file on your system 
terminal. (Remember that you may use the space bar to suspend or resume display on a CRT 
terminal.) 

> COPY DEMSUB;A <CR> 

Figure 1 -3 shows the listing of the sample subroutine. 



assembler 
identification 



user-defined 
title 



Tektronix 8080/8085 ASM Vx.x SAMPLE SUBROUTINE 



Page 



source 
listing 



00002 
00003 
00004 
00005 

00006 0000 D300 

00007 0002 C9 
00008 



NAME SUBSM0D 

GLOBAL P0RTN, OUTSUB 

SECTION SUBS1 
; SUBROUTINE 0UTSUB — OUTPUTS A CHARACTER. 
OUTSUB OUT P0RTN ; 0UTSUB STARTS HERE. 

RET ; RETURN TO PROGRAM. 

END 



source 
file 
line 
number 



object 
code 



source code 



comments 



address 



Tektronix 8080/8085 ASM Vx.x Symbol Table 



Scalars 



symbol 
table 



A 0007 

H 0004 



B 0000 

L 0005 



0001 
0006 



D — 
PSW 



Page 



0002 E 

0006 SP — 



0003 
0006 



statistics 



SUBS1 Section (0003) 

OUTSUB - 0000 G 
P0RTN Unbound Global 

8 Source Lines 8 Assembled Lines 47710 Bytes available 
>>> No assembly errors detected <<< 



3454-3 



Fig. 1-3. Assembler listing for the sample subroutine. 

The command ASM DEMSUB;0 DEMSUB;A DEMSUB%S produces this listing file from the subroutine 
source file. The command COPY DEMSUB;A LPT1 copies the listing file to the line printer. 

Every assembler listing has two parts: the source listing and the symbol table. Each page of 
the listing begins with a standard page heading, 
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The Source Listing 

Page 1 of your assembler listing contains the source listing. The heading includes the words 
"SAMPLE SUBROUTINE", which you supplied with the TITLE directive. 

Each line of the source listing contains the following information: 
1. the line number (decimal); 



the memory location (hexadecimal) of the object code generated (if any); 

the assembled object code (hexadecimal); 

a relocation indicator (>) if the object code may be adjusted by the linker; 

a text substitution indicator (+) if the assembler has modified the source statement 
(this demonstration gives no examples of text substitution); 

6. the source statement. 

If any statement contains an error, the appropriate error message appears directly after the 
statement. 

Examine each line of your source listing: 

• Line 1 (the TITLE directive) is not printed because it is a listing control directive. 

• Lines 2, 3, 4, and 8 are assembler directives that produce no object code. The 
information they provide is stored in special areas of the object module. 

• Line 5 is a comment. 

• Lines 6 and 7 are 8080A assembly language instructions: 

— The 8080A instruction OUT PORTN produces the two-byte machine instruction D300. 
D3 is the hexadecimal operation code for the OUT instruction. The dummy value 00 
will be used for the port number until the linker supplies a value for PORTN. The 
machine instruction D300 is stored in bytes 0000 and 0001 of section SUBS1. 

— The 8080A instruction RET produces the one-byte machine instruction C9, which is 
stored in byte 0002 of section SUBS1. 



The Symbol Table 

Page 2 of your listing contains the symbol table, which indicates the value and type of each, 
symbol in your source code. 

The assembler symbol table is divided into the following categories: 

1. Strings and macros 

2. Scalars (numeric values other than addresses; includes undefined symbols) 

3. Sections (and addresses within each section) 

4. Unbound globals 
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Examine the symbol table in your listing: 

1. The strings and macros table is omitted, since the sample subroutine uses neither 
string variables nor macros. 

2. The scalars table lists every scalar in the symbol list and the value associated with 
each scalar. The sample subroutine defines no scalars, but the names of the 8080A 
registers are pre-defined symbols and thus always appear in the symbol list. 

3. SUBS1 is the only section in the sample subroutine. The line 

SUBS1 Section (0003) 

tells you the following attributes of section SUBS1: 

• its name: SUBS1; 

• its section type: SECTION (as opposed to COMMON or RESERVE); 

• its relocation type: byte-relocatable (the default relocation type is implied when no 
other relocation type is specified); 

• its length: 3 bytes. 

OUTSUB has the value OOOO because OUTSUB is the address of the first byte in 
section SUBS1. The letter "G" indicates that OUTSUB is a global symbol. 

4. PORTN is the only unbound (undefined) global symbol in the subroutine. 

The statistics at the bottom of the symbol table are the same statistics that appeared on the 
system terminal when the assembler finished execution. 

When there are errors in your source code, the two most useful parts of your listing are the 
source listing and the scalars table. The source listing contains the error messages and 
shows the erroneous lines in context with the rest of the program. The scalars table flags 
undefined symbols with the value "****", 

Create the Main Program Source File 

Now that you have created, corrected, and assembled the sample subroutine, it is time to 
create the main program that uses the subroutine. Enter the following command to begin the 
editing session that creates the main program source file, DEMPRO%S: 

> EDIT DEMPR0%S <CR> 

** EDIT VER x.x ** 
**NEW FILE** 
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Declare the editor tab character and type in the source code, just as you did for the 
subroutine. (This time, however, don't include any typing errors.) 

»TAB $ <CR> 

*INPUT <CR> 

INPUT: 

$GLOBAL$PORTN, OUTSUB <CR> 

P0RTN$EQU$15$: PORT = 15 <CR> 

START$MVI$A,"?"$; CHARACTER = "?" <CR> 

$CALL$OUTSUB$ * SEND "?" TO PORT 15... <CR> 

$HLT$$; ... AND STOP. <CR> 

$END$START <CR> 

<CR> 

Inspect the text you have entered to be sure there are no errors: 

*TYPE B-E <CR> 





GLOBAL 


PORTN, 


OUTSUB 


PORTN 


EQU 


15 


; PORT = 15 


START 


MVI 


A " ? " 


; CHARACTER = "?" 




CALL 


OUTSUB 


; SEND "?" TO PORT 15 




HLT 




; ... AND STOP. 




END 


START 





Enter the FILE command to save the text onto the source file and return to TEKDOS: 

* FILE <CR> 
*DOS* EOJ 



Assemble the Main Program 

Enter the following command line to create an object file (DEMPRO;0) and a listing file 
(DEMPRO;A) from the main program source file: 

> ASM DEMPRO;0 DEMPRO;A DEMPRO%S <CR> 

Tektronix 8080/8085 ASM Vx.x 
**** Pass 2 

6 Source Lines 6 Assembled Lines 47733 Bytes available 

>>> No assembly errors detected <<< 
*ASM* EOJ 

> 
The main program contains no errors. 
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Examine the Main Program Listing 

Copy the assembler listing to the line printer or to the system terminal: 

> COPY DEMPRO;A LPT1 <CR> 



or 



> COPY DEMPRO;A <CR> 



Tektronix 8080/8085 ASM Vx.x 



Page 



source 
listing 



00001 

00002 000F 

00003 0000 3E3F 

00004 0002 CD0000 

00005 0005 76 

00006 0000 



GLOBAL PORTN, 0UTSUB 



PORTN EQU 

START MVI 

CALL 

HLT 

END 



15 
A "?" 
0UTSUB 

START 



Tektronix 8080/8085 ASM Vx.x Symbol Table 



PORT = 15 
CHARACTER = "?" 
SEND "?" TO PORT 15. . . 
. . . AND STOP. 



Page 



Scalars 



symbol 
table 



A 0007 

H 0004 

SP 0006 



B 0000 C 0001 

L 0005 M 0006 



D 0002 E 0003 

PORTN - 000F G PSW — - 0006 



statistics 



5GDEMPR0 (default) Section (0006) 

START — 0000 
OUTSUB Unbound Global 

6 Source Lines 6 Assembled Lines 47733 Bytes available 
>>> No assembly errors detected <<< 



3454-4 



Fig. 1-4. Assembler listing for the sample main program. 

The command ASM DEMPRO;0 DEMPRO;A DEMPRO%S produces this listing file from the main 
program source file. The command COPY DEMPRO;A LPT1 copies the listing file to the line printer. 

Compare the listing of the sample main program (Fig. 1 -4) with the listing of the sample 
subroutine (Fig. 1-3). 

The Source Listing 

Page 1 of your assembler listing contains the source listing. Notice that there is no user- 
defined title for the program listing: the source code contains no TITLE directive. 

Examine each line of the program source listing. 

1 . As in the subroutine, the GLOBAL statement produces no object code. 

2. The EQU statement assigns the value 15 (OOOF hexadecimal) to the symbol PORTN. 
The symbol PORTN and its value are stored in the global symbol block of the program 
object module. At link time, the value of PORTN will be substituted into the OUT 
instruction in the subroutine. 
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3. The 8080A assembly language instruction MVI A,"?" generates the machine 
instruction 3E3F. 3E is the operation code for "MV! to A" and 3F is the ASCI! code for 
the question mark. The machine instruction 3E3F is stored in bytes 0000 and 0001 of 
the main program. 

4. The 8080A assembly language instruction CALL OUTSUB generates the machine 
instruction CD0000 in bytes 0002 through 0004. CD is the operation code for the 
CALL instruction. 0000 is a dummy value: the address of OUTSUB will be provided at 
iink time. 

5. The 8080A assembly language instruction HLT produces the one-byte machine 
instruction 76 in byte 0005 of the main program. 

6. The END statement specifies that the transfer address is 0000, the address of the MVI 
instruction. The transfer address will be adjusted if this section of object code is not 
loaded at the beginning of memory. 



The Symbol Table 

1 . The strings and macros table is again omitted because it is empty. 

2. The scalars table lists the usual pre-defined scalars, plus the symbol PORTN. The 
value of PORTN is 000F hexadecimal. The "G" indicates that PORTN is a global 
symbol. 

3. Because the main program source code contains no SECTION directive, the section 
produced by this assembler run is given the following default attributes: 

• name: %DEMPRO (derived from the name of the object file); 

• section type: SECTION; 

• relocation type: byte-relocatable. 

Section %DEMPRO contains six bytes of code. START is the address of the first byte of 
the section. 

4. OUTSUB is the only unbound (undefined) global symbol in the main program. 



The statistics at the bottom of the symbol table are the same statistics that appeared on the 
system terminal when the assembler finished execution. 
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Link the Object Modules 

Now both the subroutine and the main program have been translated into machine language. 
In order for the subroutine and main program object modules to communicate with each 
other, they must be linked. The linker performs the following tasks in creating a load file of 
executable object code: 

• It finds a block of memory for each section in the specified object files. 

• It adjusts addresses to reflect relocation of sections. 

• It provides values for unbound globals. 

Enter the following command to create a load file (DEMPRO;L) and a linker listing file 
(DEMPRO;K) from your two object files: 

> LINK DEMPRO;L DEMPRO;K DEMPRO;0 DEMSUB;0 <CR> 

The linker responds as follows: 

NO ERRORS NO UNDEFINED SYMBOLS 
2 MODULES 2 SECTIONS 
TRANSFER ADDRESS IS 0000 
•LINK* EOJ 



Examine the Linker Listing 

Copy the linker listing file to the line printer or system terminal: 

> COPY DEMPR0;K LPT1 <CR> 

or 

> COPY DEMPR0;K <CR> 

Figure 1-5 shows the linker listing. 
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TEKTRONIX 8080/8085 LINKER V x.x GLOBAL SYMBOL LIST 


PAGE 


1 


$DEMPR0 0000 OUTSUB 0006 PORTN 000F SUBS1 


0006 




ir.M«UBiA OUOU/OUOD L.1PIR.C.K V X.X MUJJULfc. MAP 


PAGE 


2 


FILE: DEMPRO;0 






MODULE: *NONAME* 

5&DEMPRO SECTION BYTE 0000-0005 






FILE: DEMSUB;0 






MODULE: SUBSMOD 

SUBS1 SECTION BYTE 0006-0008 
OUTSUB 0006 






TEKTRONIX 8080/8085 LINKER V x.x MEMORY MAP 


PAGE 


3 


0000-0005 JDEMPRO SECTION BYTE 
0006-0008 SUBS1 SECTION BYTE 






( NO ERRORS NO UNDEFINED SYMBOLS 
statistics < 2 MODULES 2 SECTIONS 
( TRANSFER ADDRESS IS 0000 




3454-5 



Fig. 1-5. Linker listing. 

The command LINK DEMPRO;L DEMPRO;K DEMPRO;0 DEMSUB;0 produces this linker listing file. The 
command COPY DEMPRO;K LPT1 copies the listing file to the line printer. 

The linker listing contains three parts: 

1 . The global symbol list (page 1 of your listing) lists the value assigned to each global 
symbol. The name and starting address of each section are included. Undefined 
globals are flagged with the value "****". 

2. The module map (page 2) provides the following information for each object module 
being linked: 

• the name of the object file or library file supplying the object module; 

• the name and attributes of each section in the module. Any entry points (addresses 
declared as global symbols) for each section are also listed. 

The module map allows you to verify that each section of your program has been 
assigned a place in memory. 

3. The memory map (page 3) lists the sections in the order they occur in memory. 
Conflicting (overlapping) memory allocations are indicated with an asterisk (*). 

Linker statistics appear at the bottom of the memory map. 



O 
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An optional feature of the linker listing, the internal symbol list, is useful for program 
debugging. The internal symbol list is not demonstrated here but is discussed in the Linker 
section. 



The Memory Map 

The memory map (page 3 of your listing) provides the most concise summary of the load file 
produced by the linker. 

The memory map shows that bytes 0000 through 0005 of memory will contain section 
%DEMPRO (the main program) and that bytes 0006 through 0008 will contain section 
SUBS1 (the subroutine). 

The memory map also gives the section type (SECTION) and relocation type (byte-relocatable) 
for each section. 

Notice that the transfer address remains unchanged because the section containing the 
transfer address is located at the beginning of memory. 



The Module Map 

The module map (page 2) shows much the same information as the memory map. The 
module map, however, reports the sections by module rather than by memory location. 

The first object file, DEMPRO;0, contains the object module called *NONAME*. (Recall that 
the main program source code contains no NAME directive.) The main program consists of 
the single section %DEMPRO, whose attributes you already know from the memory map. 

The second object file, DEMSUB;0, contains the subroutine object module, SUBSMOD. 
SUBSMOD consists of the single section SUBS1. The single entry point to SUBS1 is 
OUTSUB, whose adjusted address (after relocation) is 0006. 



The Global Symbols List 

The global symbols list (page 1 ) shows the two symbols declared in GLOBAL statements 
(OUTSUB and PORTN) and the two section names (%DEMPRO and SUBS1). 
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Demonstration: Load 



Load the Executable Object Code into Memory 
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program memory with zeros. Later, when you examine memory, the zeros make it easy to 
identify the end of your code. Enter the following command to fill memory locations 0000 
through 000F with zeros: 

> FILL F 00 <CR> 

Now copy the executable object code from the load file into program memory: 

> LOAD DEMPR0;L <CR> 
TRANSFER ADDRESS: 0000 
•LOAD* E0J 

> 

Bytes 0000 through 0008 of program memory now contain the nine bytes of machine 
language that form the executable program. 

The TEKDOS command DUMP displays the contents of a specified section of memory. Each 
byte is displayed as a two-digit hexadecimal number and as the ASCII character it represents 
(if any). Enter the following command to display the contents of memory locations 0000 
through 000F: 

> DUMP F <CR> 



0000=3E 3F CD 06 00 76 D3 OF C9 00 00 00 00 00 00 00 >? 



address of 
first byte 
displayed 



main 
program 



subroutine 



rest of memory 

not affected 

by LOAD command 



corresponding 
ASCII characters 



Compare the relocatable object code produced by the assembler with the executable object 
code produced by the linker. (The addresses and object bytes adjusted by the linker are 
underlined.) 



RELOCATABLE OBJECT CODE 


EXECUTABLE OBJECT CODE 


(from assembler listings) 


(from DUMP output) 




Object 


Source 




Object 


Source 


Address 


Code 


Code 


Address 


Code 


Code 


0000 


3E3F 


MVI A,"?" 


0000 


3E3F 


MVI A,"?" 


0002 


CD0000 


CALL OUTSUB 


0002 


CD0600 


CALL OUTSUB 


0005 


76 


HLT 


0005 


76 


HLT 


0000 


D300 


OUT PORTN 


0006 


D30F 


OUT PORTN 


0002 


C9 


RET 


0008 


C9 


RET 



(a) 
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Note the adjustments made by the linker: 

• The subroutine is relocated from byte 0000 to byte 0006. 

• The address of the subroutine is substituted into the CALL instruction. 

• The port number is substituted into the OUT instruction. 

Summary of Demonstration Run 

Enter the following command to list the files on your system disc: 

> LDIR <CR> 

FILE NAME BLKS 



16 
170 



TEKDOS 

COPYSYS 

NEWDISC 

DEMPR05&S 

DEMSUB;0 

DEMSUB;A 

DEMSUBJS 

DEMPR0;0 

DEMPR0;A 

DEMPR0;L 

DEMPR0;K 



TOTAL FILES 12 

TOTAL BLOCKS USED 196 

BLOCKS AVAILABLE 98 

TOTAL BAD BLOCKS 



Recall the eight files you have created in this Demonstration Run: 

• the two source files (DEMSUB%S and DEMPRO%S) you created using the editor; 

• the two object files (DEMSUB;0 and DEMPRO;0) and the two listing files (DEMSUB;A 
and DEMPRO;A) generated by the assembler; 

• the load file (DEMPRO;L) and the listing file (DEMPRO;K) generated by the linker. 

You have now finished the Demonstration Run. It emphasized how to: 

• create a source file, using the editor; 

• create an object file from a source file, using the assembler; 

• create a load file from object files, using the linker; 

• copy the load file into memory, using the LOAD command; 

• interpret listings generated by the assembler and linker. 

The Demonstration Run in the Learning Guide of the 8002A System Users Manual shows 
you how to execute and monitor the program you have loaded into memory. 
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FOR CONTINUED LEARNING 

This Learning Guide explained the basic concepts needed to use the assembler and linker. 
Understanding these same concepts will help you learn to use the library generator. To 
obtain a more detailed explanation of how to use these system programs, refer to the 
following sections: 



Section 2, Procedures. Gives you step-by-step instructions for accomplishing common tasks 
in assembling, linking, and library maintenance. 



Section 3, Assembler Introduction. Shows the use of the TEKDOS command ASM; reviews 
the notationai conventions used throughout this manual; explains the assembler listing in 
more detail. 



Section 4, Assembly Language Elements. Describes the fundamental elements of an 
assembly language statement; gives rules for creating symbols, constants, and expressions; 
describes special characters and assembler functions. 



Section 5, Assembler Directives. Describes the function and use of each assembler 
directive. Each description is accompanied by one or more examples. Directives are arranged 
in alphabetical order. 



Section 6, Macros. Shows how to create and use assembler macros; demonstrates the 
macro features of the Tektronix Assembler. 



Section 7, The Linker. Describes the function and use of the TEKDOS command LINK, and 
of each command in the linker subsystem; explains the linker listing in more detail. 



Section 8, The Library Generator. Describes the function and use of the TEKDOS command 
LIBGEN, and of each command in the library generator subsystem; explains the library 
generator listing. 



Section 9, Programming bxamples. Demonstrates and explains useful applications of the 
assembler, linker, and library generator. 



O 1-27 



For Continued Learning Learning Guide— 8002A: Assembler Users Manual 



Section 10, Tables. Summarizes reference information in tabular form. 



Section 1 1 , Technical Notes. Provides information on special applications of the assembler, 
linker, and library generator. 



Section 12, Assembler Specifics. Provides information that varies with each 
microprocessor: registers, instruction sets, special error messages, etc. Section 12 also 
contains Demonstration Runs for microprocessors other than the 8080A. An Irregularities 
paragraph for each microprocessor lists exceptions to the standard reference material in this 
manual. 



Section 13, Error Messages. Lists the error messages for the assembler, linker, and library 
generator. Each error message is accompanied by a description of the problem and possible 
solutions. 



Section 14, Glossary. Defines special terms used in this manual 



8002A System Users Manual. Describes how to use the 8002A /^Processor Development 
Lab and its operating system, TEKDOS. 
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Section 2 
PROCEDURES 



INTRODUCTION 

In the previous section, the Learning Guide, you were presented with the basic concepts of 
the TEKDOS Assembler and Linker. In this section, Procedures, you are shown procedures 
for using the assembler, the linker, and the library generator. 

Each procedure in this section is simply a series of one or more command entries or actions 
for you to perform. Most of the procedures contain parameters (places for values) that you 
will supply when you perform the procedure. 

Each procedure is presented in the following format: 

Description: A summary of the operation(s) performed by the procedure. 



Procedure: 



Parameters: 

Comments: 
Examples: 
See Also: 



The information entered or displayed at the system terminal. The 
following conventions are used in the procedure description: 

Underlined : The character sequence that you will enter. The sequence 
may consist of the exact characters to be entered, or parameters for 
which you must substitute your values. 

No underline: A character sequence that is displayed by TEKDOS. 

UPPERCASE: An exact character sequence; if these characters are 
underlined, enter them exactly as shown. (If they are not underlined, 
you will see these characters displayed by TEKDOS.) 

lowercase: A parameter for which you will supply a value when you 
perform the procedure. 

(Parentheses): A comment, or an action for you to perform at the 
indicated time. 

The filenames or options that you provide. If a filename is used, a slash 
"/" followed by a digit will specify the drive number. If no drive number 
is specified, TEKDOS assumes the file is on the system disc. 

The operating limits and options for this procedure. 

One or more demonstrations of the correct entry format. 

Cross-references to related procedures. 



i-or a tuii aescription ot any given commana, reTer to Assemoier Directives, LinKer, or Lmrary 
Generator section in this manual, as appropriate. 
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ASSEMBLING YOUR PROGRAM 



Invoking the Assembler 

Description: 



Procedure: 
Parameters: 



Examples: 



See also: 



This procedure generates an object file (in machine language) from an 
assembly language source file. 

> ASM objectfile listing sourcefile 

objectfile — The name of the file where the assembled object code will 
be stored. 

listing — The name of the listing file or device. 

sourcefile — The file containing the assembly source code for the 
program. 

> ASM MYFILE;0/0 MYFILE;A/1 MYFILE;S/0 

This command line assembles the source code present in the file 
MYFILE;S on drive 0. The resulting object code is placed in the file 
MYFILE;0 on drive 0. The assembler also produces a program listing and 
a list of defined symbols. This listing is placed in the file MYFILE;A on 
drive 1 . 

• Invoking the Linker 

• Displaying Internal Symbols in the Linker Listing 



Combining Source Files During Assembly 

Description: 



Procedure: 
Parameters: 



Comments: 



This procedure assembles code from several source files into a single 
object module. 

> ASM objfile listing asrcfile bsrcfile csrcfile 

objfile — The name of the file in which the object code will be stored. 
listing — The name of the listing file or device. 
asrcfile — The first source file to be assembled. 
bsrcfile — The second source file to be assembled. 
csrcfile — The third source file to be assembled. 

The command line assembles the source files in left-to-right order. An 
END statement should appear only in the last source file to be 
assembled (in this case, csrcfile). 
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Assembling Your Program 



txampie: 



See also: 



The three source files are assembled left-to-right: ASORCE;S on drive 0, 
then BS0RCE;S on drive 1, and then CSORCE;S on drive 1. The object 
code is placed in the SUMOBJ;0 file on drive 0. The program listing is 
output on the line printer (LPT1 ). 

• Invoking the Assembler 



Displaying Internal Symbols in the Linker Listing 

Description: 



Procedure: 



This procedure adds the internal symbol list to the linker listing. The 
internal symbol list contains all of the symbols in the source file and 
their final values. These interna! symbols include: scalars, section 
labels, and labels for unbound globals. This listing is useful for 
debugging high-level and assembly language programs. 

(Invoke the editor and include the LIST DBG option at the beginning of 
the assembler source file.) 

> EDIT yourfile 

** EDIT VER X.X 
* INPUT 
INPUT: 

tLISTtDBG <cr> 
<cr> 

(t represents a tab or control-l key) 

* FILE 
*EDIT* EOJ 

(Assemble the yourfile source file) 

> ASM ob jectfile ,, yourfile 

(Link the objectfile object file) 

> LINK loadfile listing objectfile 

(The loadfile may now be LOADed into program memory. The linker 
listing will show the memory addresses and the values of all symbols 
used in the program.) 



@ 
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Parameters: 



Comments: 



See also: 



objectfile — The name of the file where the assembled object code will 
be stored. 

yourfile — The name of the assembly source file that will have the LIST 
DBG option added. 

loadfile — The name of the resulting load file. 

listing — The name of the listing file or device. This listing includes a 
global symbol list and optional internal symbol or map listings. Refer to 
the Linker section of this manual for more information on the listing 
options. 

When you insert this listing control directive at the beginning of your 
assembly code the linker will list the values assigned to the internal 
symbol table. You may then examine or modify the program by using the 
linker listing to find the memory locations of symbols. 

• Invoking the Assembler 

• Invoking the Linker (Simple Invocation) 



LINKING YOUR PROGRAM 



Invoking the Linker (Simple Invocation) 



Description: This procedure converts the contents of object files (produced by the 

assembler) into a single file that is suitable for loading. 

Procedure: > LINK loadfile listing objectfile library 



Parameters: 



Comments: 



loadfile — The name of the resulting load file. 

listing — The name of the listing file or device. This listing includes a 
global symbol list and optional internal symbol or map listings. Refer to 
the Linker section of this manual for more information on the listing 
options. 

objectfile — The name of the object file from which the load file is 
generated. 

library — The name of the library file to be linked. You may omit this 
parameter. 

Additional object files may be linked by entering additional objectfile 
parameters. 
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Linking Your Program 



Examples: 



> LINK MYFILE;L MYFILE;K MYFILE;0 LIB(YOUR;Y) 

This command uses the object code stored in the file MYFILE;0 and any 
object modules selected from the YOUR;Y library file to generate a load 
file named MYFILE;L. The linker also produces a listing file named 
MYFILE;K. All files are located on the system drive, since no drive 
number was specified. 

> LINK LOADFLjL LSTFIL;K HERFIL;0 HISFIL;0 ITSFILjO 

The object code stored in the file HERFIL;0 is linked first, then the file 
HISFIUO, then last of all the file ITSFIL;0. The resulting load file is 
named LOADFL;L. The linker also produces a listing file named 
LSTFIL;K. All files are located on the system drive, since no drive 
number was specified. 



See also: 



• Invoking the Assembler 

• Invoking the Linker (Interactive Invocation) 

• Displaying Internal Symbols in the Linker Listing 



Invoking the Linker (Interactive Invocation) 

Description: This procedure converts the contents of object files (produced by the 

assembler) into a single file that is suitable for loading. This form of 
invocation also permits a series of additional commands to be given to 
the linker. 



Procedure: 



> LINK 

* LOG 

*MAP 

* LOAD loadfile 

* LIST listing 

* LINK objectfile 

* LINK library 
* — ■ 

(Enter one linker command per line) 



*END 



Parameters: loadfile — The name of the resulting load file. 

listing — The name of the listing file or device. This listing includes a 
global symbol list and optional internal symbol or map listings. Refer to 
the Linker section of this manual for more information on the listing 
options. 

objectfile — The name of the object file from which the load file is 
generated. 

library — The name of the library file to be linked. 
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Comments: 



This form of linker invocation allows you to enter commands line-by-line 
to specify: the listing format, the output file, the listing device or file, the 
input file, and several other options. These optional commands LOCATE 
sections, provide TRANSFER addresses for modules, and DEFINE values 
for symbols. If you wish to link more than one file, repeat the LINK 
command on the following line with the additional file as its parameter. 
The END command begins linker execution. For more information about 
linker invocation, see the Linker section of this manual. 



Example: 



> LINK 

*LOG 

*MAP 

*LOAD 0URFIL;L/1 

*LIST LPT1 

*LINK MYFILE;0/1 

*LINK YRFILE;0/1 

*LINK LIB(HILVL;Y) 

*DEFINE INITSP=8000 

*END 



The object code stored in the two files MYFILE;0 and YRFILE;0 (both on 
drive 1) is linked with selected object modules from the library file 
HILVL;Y. The global symbol INITSP is assigned a hexadecimal value of 
8000 and the linked body of code is placed in a load file named 
OURFIL;L. The line printer (LPT1) records the linker commands, the 
values of symbols, and the locations of sections. 

> LINK 

*L0G 

*MAP 

*L0AD 0UTFIL;L 

*LIST LSTFIL;K 

*LINK INFILE;0 

"LOCATE SECTNAME,BASE(0) 

*END 

The input file INFILE;0 contains a section named SECTNAM. The BASE 
attribute of the LOCATE command positions the starting address of this 
section at address 0. The resulting load file is named OUTFIL;L. The list 
file LSTFIL;K records the linker commands, the values of symbols, and 
the locations of sections. 



See also: 



Assigning Object Code to an Address Range 
Reserving an Area of Memory 
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Linking Your Program 



Assigning Object Code to an Address Range 

Description: 



Procedure: 



This procedure assigns an object code section to a specified address 
range. 

> LINK 

* L0G 

* MAP 

* L0AD loadfile 

* LIST listing 

* LINK objectfile 

* L0CATE sec tier name, RANGE (start ad dr , endaddr) 

*ettd 



Parameters: 



Comments: 



loadfile — The name of the resulting load file. 

listing — The name of the listing file or device. This listing includes a 
global symbol list and optional internal symbol or map listings. Refer to 
the Linker section of this manual for more information on the listing 
options. 

objectfile — The name of the object file from which the load file is 
generated. Repeat this line for each additional object file to be linked. 

sectionname — The name of the object section that is relocated into the 
specified address range. 

startaddr — The lower bound of the allowed relocation range. This 
address is specified in hexadecimal. 

endaddr — The upper bound of the allowed relocation range. This 
address is specified in hexadecimal. 

The object files to be LINKed are scanned for the section name specified 
by the LOCATE command. This object section is relocated within a 
RANGE bounded by the specified starting and ending addresses. All 
other object sections may be relocated anywhere within the processor's 
address range (this includes the specified RANGE). The LOAD command 
specifies the name of the load file. The listing may be sent to either a file 
or device. 



Example: 



> LINK 

*L0G 

*MAP 

*L0AD 0UTFIL;L 

*LIST LSTFIL;K 

*LINK INFILE;0 

*L0CATE SECTNAM,RANGE(0,FF) 

*END 
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See also: 



The input file INFILE;0 contains an object section named SECTNAM. 
The LOCATE command assigns the object section SECTNAM within a 
range of addresses to FF. This range is specified by the RANGE 
parameter. Any object sections remaining in INFILE;0 are relocated 
within the address range of the processor. The resulting linked object 
code is sent to the load file OUTFIL;L. The linker commands are recorded 
in the file LSTFIL;K, along with the values of symbols and the locations 
of sections. 

• Reserving an Area of Memory 

• Invoking the Linker (Interactive Invocation) 



Reserving an Area of Memory 

Description: This procedure prevents relocation within a predefined address range. 

Procedure: (Create a dummy source file with an absolute section:) 

Label Operation Operand 



SECTION 
ORG 
BLOCK 
END 



dummyrame .ABSOLUTE 

startaddr 

areasize 



(Assemble an object file from the dummy source file:) 

> ASM skipob ject , , skipscurce 

(Link skipobject and your object file:) 

> LINK loadfile listing skipobject yourobject 



Parameters: 



dummyname — The name of the dummy section. The SECTION 
statement includes an ABSOLUTE option. This option directs the linker 
to use the address specified by the ORG directive as the starting address 
in memory. The operand of the BLOCK directive specifies the size of the 
reserved block of memory. 

startaddr — The starting address of the reserved area. 

areasize — The size of the reserved area. 

skipsource — The name of the dummy source file. 

skipobject — The assembled dummy file. 

yourobject — The object file containing your program. 

listing — The name of the listing file or device. This listing includes a 
global symbol list and optional internal symbol or map listings. Refer to 
the Linker section of this manual for more information on the listing 
options. 

loadfile — The name of the resulting load file. 
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Comments: A dummy file is linked with the object file containing your program. The 

ABSOLUTE option within the dummy section directs the linker to start 
the section at the address specified by the ORG directive. The BLOCK 
directive specifies the size of the reserved area. The object sections of 
your program are then relocated around the reserved area occupied by 
the dummy section. This reserved area may be used for ROM storage or 
memory-mapped I/O. 

Example: (Create a source file SKIP;S with the text editor:) 

Label Operation Operand Comment 



SECTION 


SKIPSEC, ABSOLUTE; 


ORG 


; Base Address 


BLOCK 


100H ; Reserved Memory 


END 





(Assemble the source file SKIP;S:) 

> ASM SKIP;0, ,SKIP;S 

(Link SKIP;0 and your object file) 

> LINK YRFILE;L LPT1 SKIP;0 YRFILE;0 

The dummy file SKIP;S is assembled and renamed SKIP;0. This object 
file is linked with the object file YRFILE;0. The ABSOLUTE option within 
the dummy section SKIPSEC directs the linker to start the section at 
address (as specified by the ORG directive). The BLOCK directive then 
reserves a specified area of 100 (hexadecimal) bytes. 

The linker relocates the remaining object sections around the SKIPSEC 
dummy section, leaving the first 256 bytes of memory unused by this 
program. The resulting load file is named YRFILE;L. The listing device is 
the line printer (LPT1). 

See also: • Invoking the Linker (Interactive Invocation) 
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BUILDING AND MAINTAINING A LIBRARY 



Invoking LibGen 

Description: 

Procedure: 



This procedure shows the general format for invoking the library 
generator (LibGen). 

> LIBGEN newlib listing oldlib 
* (Enter one LibGen command per line) 



Parameters: 



Comments: 



Example: 



« END 

newlib — The name of the file that will contain the new version of the 
library. 

listing — The name of the listing file or device. 

oldlib — The name of the old library file. 

When you invoke LibGen you may use one or more commands to 
INSERT, EXTRACT, REPLACE, or DELETE library modules. If these 
commands are not entered, oldlib will be copied into newlib without 
modification. The END command must always terminate the invocation. 
For more information, see the Library Generator section of this manual. 

> LIBGEN BIGLIB;Y LSTLIB;N SMLLIB;Y 
*INSERT BIG; 0/1 

*END 

The library file SMILLIB;Y is copied into a new library file named 
BIGLIB;Y. The object module in file BIG;0 on disc drive 1 is inserted at 
the beginning of the BIGLIB;Y library file. The LSTLIB;N file lists the 
modules within the output library, the global symbols within each each 
module, and the actions performed by the library generator. 

> LIBGEN, ,LSTLIB;N ADLIB;Y 
*END 



See also: 



The module names in the library file ADLIB;Y are sent to the listing file 
LSTLIB;N. This file may be copied to the system terminal (CONO) or a 
line printer (LPT1). 

• Creating a User-Defined Library 

• Adding a New Library Module 

• Examining a Library Module 

• Replacing a Library Module 

• Combining Libraries 
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Building and Maintaining a Library 



Creating a User-Defined Library 

Description: This procedure creates a new library from object modules. 



Procedure: 



> LIBGEN newlib listing 

*INSERT objectfile (repeat as necessary) 



Parameters: 



newlib — The name of the new library file. 

listing — The name of the listing file or device. 

objectfile — One of the files containing the object modules to be included 
in the library. Enter one INSERT command for each object file to be 
inserted. 



Comments: 



Each object module in the library should be uniquely named (with the 
NAME directive) at assembly time. If you do not name the object 
modules, you will not be able to modify or maintain the library. 

For more information about naming modules, refer to the NAME 
directive in the Assembler Directives section of this manual. 



Example: 



> LIBGEN MYLIB;Y LSTLIB;N 
*INSERT AFILE;0/1 
*INSERT BFILE;0/1 
•INSERT CFILE;0/1 
•INSERT ZFILE;0/1 
*END 



The library file MYLIB;Y is created on the system disc. The library file 
contains object modules from files AFILE;0, BFILE;0, CFILE;0, and 
ZFILE;0 (all on drive 1). The LSTLIB;N file lists the modules within the 
new library, the global symbols within each module, and the actions 
performed by the library generator. 



See also: 



Adding a New Library Module 
Combining Libraries 



2-11 



Building and Maintaining a Library 



Procedures— 8002A: Assembler Users Manual 



Adding a New Library Module 

Description: 



Procedure: 



Parameters: 



Comments: 



Example: 



This procedure copies a library and inserts an object module from a file 
into the new library. 

(Add a module at the beginning of a library) 

> LIBGEN rewlib listing oldlib 

* INSERT addfile 

*END 

newlib — The file that will contain the new version of the library. 

listing — The name of the listing file or device. 

oldlib — The name of the old library file. 

addfile — The name of the file containing the object module that is added 
to the library. 

Each object module in the library should have a unique name given at 
assembly time. If you do not name the object modules, you will not be 
able to modify or maintain the library. 



> LIBGEN ADLIB;Y LPT 1 MYLIB;Y 

*INSERT DFILE;0/1 

*END 



See also: 



The MYLIB;Y library is copied into ADLIB.Y. The object module within 
DFILE;0 (residing on disc drive 1) is inserted at the beginning of the 
library. The LSTLIB;N file lists the modules within the output library, the 
global symbols within each each module, and the actions performed by 
the library generator. 

• Examining a New Library Module 

• Replacing a Library Module 
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Building and Maintaining a Library 



Extracting a Library Moduie 

Description: This procedure copies a library module into an object file. 



Procedure: 



> LIBGEN, ,listirg lib 
* EXTRACT mcdlib TO newfile 
*END 



Parameters: 



Comments: 



listing — The name of the listing file or device. 

lib — The name of the library file. 

modlib — The name of the library module that will be copied into a new 
file. 

newfile — A new file used to store the extracted library module. 

You may use additional procedures to examine the code within the 
object file newfile. Refer to the Procedures section of the 8002A System 
User's Manual. 



Example: 



See also: 



> LIBGEN, ,LPT1 ADLIB ;Y 
*EXTRACT AMOD TO XFILE;0/1 
*EXTRACT BMOD TO YFILE;0/1 
*END 

Two modules are copied from the library file ADLIB;Y into two object 
files. AMOD is copied into the object file XFILE;0 on drive 1; BMOD is 
copied into the object file YFILE;0 on drive 1 . The line printer (LPT1 ) lists 
the modules within the library, the global symbols within each each 
module, and the actions performed by the library generator. 

• Adding a New Library Module 

• Replacing a Library Module 



Replacing a Library Module 

Description: This procedure replaces an existing library module with a new one. 

Procedure: > LIBGEN newlib listing oldlib 

* REPLACE modlib BY newfile 
* END 

Parameters: newlib — The file that will contain the new version of the library. 

listing — The name of the listing file or device. 

oldlib — The name of the old library file. 

modlib — The name of the library module that will be replaced by the 
new module. 

newfile — The file name of the new module. 
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Comments: 



The new library is scanned for modlib, which is then deleted and 
replaced by the object module within newfile. 

Each object module in the library should have a unique name given at 
assembly time. If you do not name the object modules, you will not be 
able to modify or maintain the library. For more information about 
naming modules, refer to the NAME directive in the Assembler 
Directives section of this manual. 



Example: 



> LIBGEN NULIB;Y LSTLIB;N ADLIB;Y 

*REPLACE AMOD BY XFILE;0/1 

*REPLACE BMOD BY YFILE;0/1 
*END 



See also: 



The ADLIB;Y library is copied into NULIB;Y. The object module within 
XFILE;0 (on drive 1) replaces AMOD, and the object module within 
YFILE;0 (on drive 1) replaces BMOD. The listing file LSTLIB;N lists the 
contents of the new library and the actions performed by the library 
generator. 

• Examining a Library Module 

• Adding a New Library Module 



Combining Libraries 

Description: This procedure adds the contents of a small library to a larger library. 

Procedure: 



> LIBGEN. 


, , oldlistirg smallib 


•EXTRACT 


modi TO filel 


•EXTRACT 


mod2 TO file2 


•EXTRACT 


modx TO filex 



•END 



(All of the modules in the smaller library have been copied into 
individual files.) 

> LIBGEN newlib rewlistirg biglib 
• INSERT filel 
•INSERT file2 



• INSERT filex 
•END 
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Parameters: oldlisting — The name of the listing file or device that shows the 

contents of the old library. 

smallib — The name of the smaller library file. 

modi, mod2, ..., modx — The library modules extracted out of the 
smaller library. 

filel, file2, ...,filex — The individual files used to store the modules 
extracted from smallib. 

newlib — The name of the new library created from the combination of 
smallib and biglib. 

newlisting — The name of the listing file or device that shows the 
contents of the new library. 

biglib — The name of the larger library file. 

Comments: This procedure copies all of the modules modi, mod2, ..., modx from 

the smallib library into individual object files filel, file2, ..., filex. The 
biglib library is copied into the new library file newlib. The files filel, 

file2 filex are then inserted into the beginning of the newlib library. 

The first listing shows the contents of the smallib library and the second 
listing shows the contents of the newlib combined library. 



Example: > LIBGEN,, 0LDLST;N MYLIB;Y 

*EXTRACT AMOD TO AFILE;0/1 
*EXTRACT BMOD TO BFILE;0/1 
*EXTRACT CMOD TO CFILE;0/1 
*END 

> LIBGEN NULIB;Y NEWLST;N YRLIB;Y 

*INSERT AFILE;0/1 

♦INSERT BFILE;0/1 

*INSERT CFILE;0/1 

*END 

Modules AMOD, BMOD, and CMOD are copied from the MYLIB;Y library 
into intermediate object files AFILE;0, BFILE;0, and CFILE;0. These 
intermediate files are on drive 1. The YRLIB;Y library is copied into a 
new library named NULIB;Y. The intermediate files are then inserted at 
the beginning of the NULIB;Y library. The listing file OLDLST;N lists the 
contents of the old library and the actions of the first LIBGEN command; 
the listing file NEWLST;N lists the contents of the new library and the 
actions of the second LIBGEN command. 



See also: • Examining a Library Module 

• Adding a New Library Module 

• Invoking LIBGEN 
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Section 3 
ASSEMBLER INTRODUCTION 

INTRODUCTION 

The assembler translates assembly language statements (source code) into machine 
instructions (object code). The resulting object module, stored on a disc file, is suitable for 
input to the linker or to the library generator (LibGen). 

This section describes the Tektronix Assembler, and is divided into the following subsections: 

• Syntax Notation. Describes the syntax conventions used throughout this manual. 

• Assembler Invocation. Describes how to invoke the assembler with the TEKDOS ASM 
command. 

• Assembler Input. Describes how the source module is used as input to the assembler. 

• Assembler Execution. Describes the operations performed by the assembler. 

• Assembler Output. Describes the output of the assembler: the object module and the 
assembler listing. Includes an annotated assembler listing of a sample program. 



O T JV I A^/V IV KJ I f\ i 1 %J lm 

Introduction 

This manual uses syntax blocks to present: 

• TEKDOS commands, 

• linker commands, 

• LibGen commands, 

• assembler directives, and 

• assembler functions. 

The conventions used in the syntax blocks are described in this subsection. Figure 3-1 
illustrates a sample syntax block. 



SYNTAX 

ram2l 
COMMAND paraml [/par-one] [_. pB J |param3 ) ... 



r,PA"l ( param2 \ 
LpbJIi 



3454-6 
Fig. 3-1. Sample syntax block. 



mis iiyure illustrates o syntax bluck for a sample TEKDOS command line. 
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In this fictitious example, COMMAND represents a command name. PA, PB, paraml, 
param2, param3, and par-one represent the command parameters. 

Delimiters (usually spaces or commas) separate the parameters from the command name 
and from each other. 



Command Name 

A command name is a word that represents a TEKDOS command or assembler directive. 
Uppercase characters in the command name must be entered exactly as shown. When part 
of the command name is underlined, you may enter that shortened form. In Fig. 3-1, the 
short form of the command is COM. 



Parameters 

Parameters specify or modify how the command is executed. Parameters may be names, 
addresses, devices, numbers, characters, or symbols. Capitalized parameters and any special 
characters, such as the comma, parentheses, "at" sign (@), slash (/), and equals sign (-), 
must be entered exactly as they appear in the syntax block. 

Lowercase parameters are descriptive terms that identify the type of information to be 
entered. Allowable entries appear in the PARAMETERS explanation for each command. In 
this manual, parameters are sometimes represented in a syntax block by two words, joined 
with a hyphen. The hyphen shows that they are not two separate parameters. In the 
example, "par-one" represents one parameter. 

Parameters may be required or optional in the command line. Required parameters appear in 
the command line without braces or brackets. For example, "paraml" is a required 
parameter. 



Optional Parameters 

Optional parameters are enclosed in brackets [ ] in the syntax block. In Fig. 3-1 "/par-one" is 
an optional parameter. The special character slash (/) is required if "par-one" is used. 



Choice of Parameters 

Parameters are stacked one above another when there is a choice of two or more 
parameters. If the parameters are stacked within braces {}, one of the parameters must be 
selected. In the example, either "param2" or "param3" must be selected. If the parameters 
are stacked within brackets [], the selection is optional. In the example, you may select either 
"PA" or "PB" or neither. Notice that if either "PA" or "PB" is selected, it must be preceded by 
a comma. 
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Repeated Parameters 

When three dots follow a parameter, the parameter may be repeated any number of times up 
to the end of the current line. The choice of "param2" or "param3" may be repeated as many 
times as the line permits. 

ASSEMBLER INVOCATION 

The assembler is invoked by the TEKDOS command ASM. 



SYNTAX 
ASM [object] [listing] source... 



PARAMETERS 

object The name of the file or device on which the object module is to be 

written. If this parameter is omitted, no object module is created. When 
the object is a file, the following syntax is used: 

file-name [ /disc-drive] 
If the disc-drive is not specified, the system disc is assumed. 

listing The file or device on which the assembler listing is to be written. If this 

parameter is omitted, no listing is created. When the listing is a file, the 
following syntax is used: 

f ile-name[ /disc- drive] 

If the disc-drive is not specified, the system disc is assumed. The listing 
can be printed directly to the line printer, by specifying LPT1 as the 
listing device. 

source The name of the file or device from which the source code is read. If the 

source is a file, the following syntax is used: 

file-name[ /disc-drive] 

If the disc-drive is not specified, the system disc is assumed. 

EXPLANATION 

The ASM command invokes the Tektronix Assembler. The source code residing on one or 
more files is translated into object code (machine language), which is stored on the specified 
object file or device. An assembler listing is generated and written on the specified file or 
device. If either the object or listing is omitted, you must enter two commas. If both are 
omitted, you must enter three commas. (See the Examples.) 

The assembler makes two passes through the source code. (See the Assembler Execution 
subsection in this section.) If you are entering the source code from a device, you must enter 
the source code twice, once for each assembler pass. 
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EXAMPLES 

ASM MYPROG;0 MYPROG;A MYPROG;S 

This example assembles the source file MYPROG;S, creating the object file MYPROG;0. The 
assembler listing is stored in the file MYPROGA All files reside on the system disc. 

ASM,,LPT1 MYPROGjS 
This example assembles the source file MYPROG;S but does not generate an object file. The 
assembler listing is output to the line printer. 

ASM, ,,MYPR0G;S/1 

This example assembles the source file MYPROG;S that resides on disc drive 1 , but does not 
generate an object file or an assembler listing. This form of invocation might be used when 
errors are suspected in the source file. The errors are listed on the system terminal. 

ASSEMBLER INPUT 

Assembler input consists of assembly language statements, as defined in the Language 
Elements section of this manual. There are three types of assembler language statements: 

• assembly language instructions, 

• assembler directives, and 

• macro invocations. 

Blank lines and comment lines (lines beginning with a semicolon) may be included in the 
input, but have no effect on the assembler. Any other assembler input will cause an error. 

If the assembler input resides in one or more source files, each file name must be specified 
in the ASM command line. If the input is read from a device, the statements must be entered 
twice. When the assembler is ready to read the source code a second time, it displays the 
following message on the system terminal: 

**** Pass 2 

If the statements entered on the second pass are not identical to those entered on the first 
pass, assembly errors will result. 
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ASSEMBLER EXECUliuN 
Two Passes 

The assembler makes two passes over the input. During the first pass, the assembler: 

• examines each statement, records any symbol it encounters in a symbol table, and 
assigns a value to each symbol. That value is used in the second pass. 

When the END statement or the end of the last source file is encountered, the assembler 
reads the input again. During the second pass, the assembler: 

• generates an object module, 

• generates a listing file, and 

• lists on the terminal any error messages generated. (See the LIST directive in the 
Assembler Directives section of this manual.) 

Forward Referencing 

Since the assembler generates a symbol table on the first pass, your programs can include 
forward referencing. For example: 

JMP DOWN 



DOWN CALL OUTS 

The symbol DOWN can be referenced before it is defined. If any symbol has a different value 
during the second pass, a phase error results. 

Execution Sequence 

As the assembler reads each statement of the source program, it performs the following 
steps: 

1. Makes any necessary text substitution. The assembler replaces any text substitution 
construct, such as "T, '(§)', or 'VARNAME', with the parameter, symbol, or string that 
the construct stands for. (See the Language Elements section of this manual.) 

2. Performs the indicated action according to the type of statement: 

a. assembly language instruction— The assembler translates each assembly 
language instruction into the corresponding machine instruction. 

b. assembler directives — Performs the action specified by the directive. Not all 
assembler directives produce object code. (See the Assembler Directives section 
of this manual for the effect of individual directives.) 

For example, some directives may simply define assembler symbols, while some 
may alter the processing order of the statements. An IF directive causes a block 
of code to be assembled or skipped depending on the true/false value of the IF 
condition. When a MACRO directive is encountered, the assembler simply stores 
the macro definition. 
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c, macro invocation — The assembler processes each statement within the 
previously defined macro. (See the Macros section of this manual.) 

The REPEAT directive within a macro causes a block of statements to be 
assembled more than once. (See the REPEAT directive in the Assembler 
Directives section of this manual.) 

ASSEMBLER OUTPUT 

The assembler generates an object module and an assembler listing. Any assembler errors 
are displayed to the system terminal. 



Object Module 

The assembler generates an object module which is stored in binary format. This assembler- 
created object module is suitable for one of the following uses: 

• It may be linked with other modules to form an executable load file. (See the Linker 
section of this manual.) 

• It may be inserted into a library file. (See the Library Generator section of this manual.) 

• It may be loaded into program memory and executed provided that the module does not 
contain any unbound global symbols and does not contain any sections that must be 
relocated. (See the Linker section of this manual for information on relocatable 
sections.) 

Assembler Listing 

The assembler generates an assembler listing consisting of two parts: the source listing, and 
the symbol table. Figure 3-2 shows the assembler listing of a sample program. Both the 
listing and the sample program that generates it are examined in more detail later in this 
section. 

The assembler listing shown in Fig. 3-2 consists of three pages: pages 1 and 2 show the 
source listing, which includes the source program and the object code generated for each 
statement; page 3 shows the symbol table. Refer to Fig. 3-2 as you read the following 
descriptions. 

Source Listing 

Each line of the source listing contains the following information: 

1. the line number (decimal). 

2. the memory location (hexadecimal) of the object code generated (if any). 

3. the assembled object code (hexadecimal). 

4. a relocation indicator (>) if the object code is to be adjusted by the linker. 

5. a text substitution indicator (+) if the assembler has modified the source statement. 

6. the source statement. 

If any statement contains an error, the appropriate error message appears directly after the 
statement. 
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Symboi labie 

The assembler symboi table displays the value and type of each symbol. The symbol table is 
divided into the following groups: 

1. Strings and Macros — Symbols that are declared as string variables or defined as 
macro names are listed in this group. The letter "S" after the symbol indicates a string 
variable and "M" indicates a macro. A number (in hexadecimal) follows each symbol. 
That number represents the number of bytes required by the assembler to store the 
character string or macro definition. 

2. Scalars — Scalar symbols are listed in this group. The letter "G" following the symbol 
indicates a global symbol. The letter "V" indicates a variable defined with the SET 
directive. The number that follows the symbol is the value assigned to the symbol. The 
value for each variable is the last value assigned to the variable during assembly. 
»****» indicates an undefined symbol. 

3. Sections — Each section of the program is listed alphabetically in this group. The 
following information appears with each section: 

• Section type— SECTION, RESERVE, or COMMON. See the Linker section of this 
manual for the definition of section types. 

• Relocation type— PAGE, INPAGE, ABSOLUTE, or, if not specified, byte-relocatable. 

• Length of section — the number of bytes of object code generated (in hexadecimal). 

• All address symbols within the section — each with its address relative to the 
beginning of the section. "E" indicates that the ENDOF function is used to 
determine the address. "H" indicates that the HI function is used and "L" indicates 
that the LO function is used. 

4. Unbound Globals — Symbols used in this module but defined elsewhere are listed in 
this group. Any symbols based on an unbound global are listed below that global. 

5. Statistics — Two summary lines of statistics appear at the end of the symbol table. The 
first line shows the number of source lines, the number of assembled lines, and the 
number of available bytes. The number of available bytes indicates the amount of 
space remaining in the assembler for storage of string variables, macros, and labels. 
The second line indicates the number of errors and undefined symbols, if any. These 
lines of statistics also appear on the system terminal at the end of the assembly 
process. 
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Tektronix 8080/8085 ASM Vx.x 


SAMPLE PROGRAM Page 


1 




object 












code 










memory 


relocation 








location 


i 


ndicator (>) 








line 
















number 






text substitution 


source 




1 








indicator ( 


*■) 


statements 




r\r^r^\ 


\r 




^ 


00002 






LIST 


TRM 




00003 






STRING 


VOTERS(20),MYSELF(20) 




00004 






STRING 


SENTENCE (40) 




00005 


03E8 


SEATS 


SET 


1000 




00006 




MYSELF 


SET 


"KEN DEDATE" 




00007 




VOTERS 


SET 


"ENGINEERS" 




00008 


00C6 


CONTRIB 


SET 


198 




00009 




; DEFINE 


RESERVE 


SECTION "SEATING". 




00010 


FFFF 




IF 


HI (CONTRIB) = 




00011 






WARNING 


; CONTRIBUTION TOO SMALL 




• •*•« 


ERROR 001: 










00012 


01F4 


SEATS 


SET 


SEATS - 500 




00013 






ENDIF 






00014 






RESERVE 


SEATING, SEATS 




00015 










-v 


00016 




; DEFINE 


MACRO "PROMISE". 


^ 




00017 






MACRO 


PROMISE 






00018 




; THIS MACRO CONCATENATES ALL PARAMETERS INTO 






00019 




; A SINGLE SENTENCE. 






00020 




SENTENCE 


SET 


1111 






00021 




PARAM 


SET 


1 ; POINT TO FIRST PHRASE. 


V macro 
/ definition 


00022 






REPEAT 


PARAM <= •#' ; REPEAT 


00023 




SENTENCE 


SET 


SENTENCE:" ":' PARAM' ; FOR 






00024 




PARAM 


SET 


PARAM + 1 ; EACH 






00025 






ENDR 


; PHRASE. 






00026 






ASCII 


"'SENTENCE'" 






00027 






ENDM 




J 




00028 












00029 


0000 000000 




DELIBERATE ERROR 




«•*»• 


ERROR 039: Invalid opera 


tion code 






00030 




; DEFINE 


PROGRAM 


SECTION "CAMPAIGN". 




00031 






GLOBAL 


SPEAK, KISSBABY 




00032 






SECTION 


CAMPAIGN 




00033 


0008 


> ELECTION 


EQU 


ENDOF(CAMPAIGN) 




00034 


0001 


> NEXTBABY 


EQU 


KISSBABY + 1 




00035 


0000 CD0000 


> FIRST 


CALL 


SPEAK 




00036 


0003 CD0000 


> THEN 


CALL 


KISSBABY 




00037 


0006 C30100 


> LAST 


JMP 


NEXTBABY 




00038 




; DEFINE 


COMMON SECTION "SPEECH". 




00039 






COMMON 


SPEECH, ABSOLUTE 




00040 


0100 




ORG 


100H 




00041 


0100 0080 


APPLAUSE 


BLOCK 


80H 




00042 


0180 


MESSAGE 


EQU 


$ 


macro 


00043 






PROMISE 


VOTERS, "WILL ALWAYS HAVE" 


invocation 




0180 20454E47 


+ 


ASCII 


" ENGINEERS WILL ALWAYS HAVE" 




0184 494E4545 












0188 52532057 












018C 494C4C20 












0190 414C5741 












0194 59532048 












0198 415645 










00044 






PROMISE 


"A FRIEND IN", MYSELF,"." 






019B 20412046 


+ 


ASCII 


" A FRIEND IN KEN DEDATE ." 
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Fig. 3-2. Sample Assembler Listing (Sheet 1 of 3) 



This sample assembler listing, and the source program that generated it, are discussed in the text. 
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Assembler Output 



Tektronix 


8080/8085 ASM Vx.x 


SAMPLE 


'R0GRAM Page 2 








019F 


5249454E 












01A3 


4420494E 












01A7 


204B454E 












01AB 


20444544 












01AF 


41544520 












01B3 


2E 










000145 






PROMISE 


"TELL YOUR FELLOW" .VOTERS 








01B4 


2054454C + 


ASCII 


" TELL YOUR FELLOW ENGINEERS" 








01B3 


4C20594F 












01BC 


55522046 












01C0 


454C4C4F 












01C4 


5720454E 












01C8 


47494E45 












01CC 


455253 






*\ 




00046 






LIST 


ME ; SHOW FULL MACRO EXPANSION 






00047 




SENTENCE 

0001 PARAM 
FFFF + 

+ SENTENCE 

0002 PARAM 

FFFF + 


PROMISE 

SET 

SET 

REPEAT 

SET 

SET 

ENDR 

REPEAT 


"TO VOTE FOR", MYSELF,"." 
n 11 

1 ; POINT TO FIRST PHRASE. 
PARAM <= 00003 5 REPEAT 
SENTENCE:" ":"TO VOTE FOR" ; FO 
PARAM + 1 ; EACH 

; PHRASE. 
PARAM <= 00003 ; REPEAT 










+ SENTENCE 


SET 


SENTENCE:" ":MYSELF ; FOR 




complete 






0003 PARAM 


SET 


PARAM + 1 ; EACH 










ENDR 


; PHRASE. 




\ macro expansion 
/ listed 






FFFF + 


REPEAT 


PARAM <= 00003 ; REPEAT 








+ SENTENCE 


SET 


SENTENCE:" ":"." ; FOR 










0004 PARAM 


SET 
ENDR 


PARAM + 1 ; EACH 

; PHRASE. 








01CF 


20544F20 + 


ASCII 


" TO VOTE FOR KEN DEDATE ." 








01D3 


564F5445 












01D7 


20464F52 












01DB 


204B454E 












01 DF 


20444544 












01E3 


41544520 












01E7 


2E 






J 




00048 






END 
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Fig. 3-2. Sample Assembler Listing (Sheet 2 of 3). 



This sample assembler listing, and the source program that generated it, are discussed in the text. 
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Tektronix 


3080/8085 ASM Vx.x Symbo 


L Table 




Page 


3 


Strings and 


Macros 










^ 


MYSELF - 
VOTERS - 


0014 S 
0014 S 


PROMISE 


0135 M 


SENTENCE 


0028 S 


\ strings 

/ and macros 


Scalars 












N 


A 

CONTRIB 

E 

M 

SEATS — 


0007 
00C6 V 
0003 
0006 
01F4 V 


B 

D 

H 

PARAM — 
SP 


0000 
0002 
0004 
0004 V 
0006 


c 

DELIBERA 
L 

PSW 


0001 
• «*• 

0005 
0006 


) scalars 


% (default) 


Section (0003) 










^ 


CAMPAIGN Section (0009) 














ELECTION 
THEN — - 


0008 E 
0003 


FIRST — 


0000 


LAST — - 


0006 




) sections 


SEATING Reserve (01F4) 












SPEECH Common Absolute (01E8) 












APPLAUSE 


0100 


MESSAGE 


0180 






J 




KISSBABY Un 


bound Global 










-\ 


NEXTBABY 


0001 










I unbound 
/ globals 


SPEAK Unbound Global 










J 


48 Source Lines 108 


Assembled 


Lines 47025 


Bytes avai 


Lable 


) statistics 


2 ERRORS 1 


UNDEFINED 


SYMBOLS 






J 
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Fig. 3-2. Sample Assembler Listing (Sheet 3 of 3). 



This sample assembler listing, and the source program that generated it, are discussed in the text. 
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Sample Source Program 



Sample Source Program 

Figure 3-3 shows the sample source program that generated the assembler listing shown in 
Fig. 3-2. The program has no practical application, but is purposely contrived to illustrate a 
variety of listing features. 





TITLE 


"SAMPLE PROGRAM" 




LIST 


TRM 




qTDTujn 

OlllJ. litvj 


V \J A U 11 O \ C\J / |I'UJ1jU1 \C-\J / 




STRING 


SENTENCE (40) 


SEATS 


SET 


1000 


MYSELF 


SET 


"KEN DEDATE" 


VOTERS 


SET 


"ENGINEERS" 


CONTRIB 


SET 


198 


; DEFINE 


RESERVE 


SECTION "SEATING". 




IF 


HI(CONTRIB) = 




WARNING 


; CONTRIBUTION TOO SMALL 


SEATS 


SET 
ENDIF 


SEATS - 500 




RESERVE 


SEATING, SEATS 


; DEFINE 


MACRO "PROMISE". 




MACRO 


PROMISE 


; THIS MACRO CONCATENATES ALL PARAMETERS INTO 


; A SINGLE SENTENCE. 


SENTENCE 


SET 


mi 


PARAM 


SET 


1 ; POINT TO FIRST PHRASE. 




REPEAT 


PARAM <= '#' 


REPEAT 


SENTENCE 


SET 


SENTENCE:" "r'PARAM 1 


FOR 


PARAM 


SET 


PARAM + 1 


EACH 




ENDR 




PHRASE. 




ASCII 


"•SENTENCE"' 




ENDM 






DELIBERATE ERROR 


; DEFINE 


PROGRAM 


SECTION "CAMPAIGN". 




GLOBAL 


SPEAK, KISSBABY 




SECTION 


CAMPAIGN 


ELECTION 


EQU 


ENDOFC CAMPAIGN) 


NEXTBABY 


EQU 


KISSBABY + 1 


FIRST 


CALL 


SPEAK 


THEN 


CALL 


KISSBABY 


LAST 


JMP 


NEXTBABY 


; DEFINE 


COMMON SECTION "SPEECH". 




COMMON 


SPEECH, ABSOLUTE 




ORG 


100H 


APPLAUSE 


BLOCK 


80H 


MESSAGE 


EQU 


$ 




PROMISE 


VOTERS, "WILL ALWAYS HAVE" 




PROMISE 


"A FRIEND IN", MYSELF,"." 




PROMISE 


"TELL YOUR FELLOW" .VOTERS 




LIST 


ME ; SHOW FULL MACRO EXPANSION. 




PROMISE 


"TO VOTE FOR", MYSELF,"." 




END 
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Fig. 3-3. Sample 8080A Source Program. 



This source program generated the sample assembler listing that was shown in Fig. 3-2. The text 
discusses each line in this source program, and the object code that it generates. 



@ 
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Sample Source Listing 

Let's compare the source program (Fig. 3-3) with the assembler listing (Fig. 3-2). The first 
line of the source program is: 

TITLE "SAMPLE PROGRAM" 

The TITLE directive creates a title on each page of the assembler program listing. The TITLE 
directive itself does not appear on the program listing and does not generate any object code. 

Tektronix 8080/8085 ASM Vx.x SAMPLE PROGRAM Page 1 

title 

The next statement in the source program is: 

LIST TRM 

The LIST directive controls various features of the assembler listing. This particular use, with 
the TRM option, prints the assembler listing in a 72-character width instead of the default 
132-character width. Although this line appears in the assembler listing, it does not generate 
object code. 

STRING VOTERSC20) ,MYSELF(20) 

STRING SENTENCE(40) 

The next two lines of source code declare the symbols VOTERS, MYSELF, and SENTENCE as 
string variables. These lines do not generate object code. The variables appear in the symbol 
table of the assembler listing (Fig. 3-2, sheet 3). The "S" following each symbol indicates a 
string variable. 



SEATS 


SET 


1000 


MYSELF 


SET 


"KEN DEDATE" 


VOTERS 


SET 


"ENGINEERS" 


CONTRIB 


SET 


198 



The SET directive assigns a value to a variable. In the first of these four SET statements, a 
numeric value is assigned to the numeric variable SEATS. The value 1000 (decimal) appears 
in the object code column (line 00005 in the assembler listing) as 03E8 hexadecimal. No 
memory location appears on the line because the value is not stored in the object program. 
MYSELF and VOTERS require string values enclosed in double quotes (" ") since they are 
string variables. The numeric value 198 (00C6H) is assigned to the numeric variable 
CONTRIB. 

; DEFINE RESERVE SECTION "SEATING". 

The semicolon (;) designates this line as a comment line. Comment lines appear in the 
assembler listing, but have no effect on the object code. 
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Sample Source Program 



IF 
WARNING 

OCT 
OC 1 

ENDIF 



HI (CONTRIB) = 
CONTRIBUTION TOO SMALL 

oca tc :n A 



These four statements are a conditional assembly block. The IF directive causes the block of 
statements between the IF and ENDIF to be assembled if the condition is true. In this case, 
the condition "HI(CONTRIB) = 0" is evaluated. The current value of the variable CONTRIB is: 

00C6H (198 decimal) 

high byte 

The function HI(CONTRIB) returns the high byte of CONTRIB (00). Since the condition value 
of the IF statement is true, the block is assembled and the statements appear on the 
assembler listing. The WARNING directive generates a user-defined error message. This 
message appears both on the terminal display during assembly and in the assembler listing. 

The SET directive changes the value of the symbol SEATS from 03E8H (1000 decimal) to 
01F4H (1000-500 decimal). See line 00012 of the assembler listing. 

RESERVE SEATING, SEATS 

This statement is an assembler directive that reserves a section in memory. The section is 
named "SEATING" and has 01F4H bytes (the current value of SEATS). The section SEATING 
appears in the symbol table of Fig. 3-2, with the word "Reserve" identifying the type of 
section. 

Next, notice the blank line in the sample program. A blank line has no effect on the object 
code, but it does generate a line in the source listing. 

; DEFINE MACRO "PROMISE". 

Although this comment line appears in the assembler listing, it has no effect on the object 
code. 



MACRO PROMISE 

; THIS MACRO CONCATENATES ALL PARAMETERS 
; A SINGLE SENTENCE. 
SENTENCE SET "" 



INTO 



PAR AM 


SET 


1 ; POINT TO FIRST I 


'HRASE. 




REPEAT 


PARAM <= '#• 


REPEAT 


SENTENCE 


SET 


SENTENCE:" ": 'PARAM' 


FOR 


PARAM 


SET 


PARAM + 1 


EACH 




ENDR 




PHRASE. 




ASCII 


"'SENTENCE'" 






ENDM 







This block of source code is a macro definition. The statements in a macro definition (with 
the exception of full comment lines) are stored by the assembler. When the macro is invoked, 
the statements within the macro are assembled, generating any indicated object code. The 
macro will be explained later, when it is invoked. 



(a) 
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Another blank line in the program code improves the readability of the program, setting the 
macro definition apart, but has no effect on the assembler. 

DELIBERATE ERROR 

This line is an invalid statement because DELIBERATE, which appears in the operation field, 
is not an assembly language instruction, an assembler directive, or a macro invocation. An 
error message is printed on the terminal and listed in the assembler listing. 

; DEFINE PROGRAM SECTION "CAMPAIGN". 
This line is another comment line and has no effect on the object code. 

GLOBAL SPEAK, KISSBABY 

The assembler directive GLOBAL declares SPEAK and KISSBABY to be global symbols. They 
are unbound globals. That is, they are used in this module, although they are defined 
elsewhere. No object code is produced. 

SECTION CAMPAIGN 

The assembler directive SECTION begins the definition of program section CAMPAIGN. The 
lines of source code following this statement define the section. 

ELECTION EQU ENDOF(CAMPAIGN ) 

The assembler directive EQU assigns a value to the symbol ELECTION. The ENDOF function 
returns the address of the last byte of a section. The assembler listing for this source line is: 

00033 0008 > ELECTION EQU ENDOF(CAMPAIGN) 

I 
relocation indicator 

The relocation indicator (>) shows that the object code for this source line (an address) will be 
adjusted by the linker at link time. Since the section CAMPAIGN is relocatable, the address of 
the last byte is undetermined until link time. The 0008, which is the value assigned to 
ELECTION, tells us that there are nine bytes (0000 through 0008) in the section. (The 
beginning address of every relocatable section is 0000 at assembly time.) 

NEXTBABY EQU KISSBABY + 1 

The assembler directive EQU assigns a value to the symbol NEXTBABY. The value assigned 
(KISSBABY + 1) is dependent on the address value of the unbound global KISSBABY. in the 
assembler listing (Fig. 3-2, line 00034), the relocation indicator again shows that the object 
code will be adjusted by the linker. The 0001 indicates that the adjusted address will be +1 
relative to the address of KISSBABY. 
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FIRST CALL SPEAK 

This statement is an 8080A assembly language instruction which caiis the subroutine 
SPEAK. The assembler listing shows the object code that is generated: 

00035 0000 CD0000 > FIRST CALL SPEAK 



address of subroutine SPEAK 
OP code of the instruction CALL 
memory location 




Since this is the first statement in section CAMPAIGN that produces object code, the memory 
location assigned is 0000. CD is the OP code for the instruction CALL. Since SPEAK is an 
unbound global variable, it does not have an address in this module. (The dummy value 0000 
appears in the object code.) The ">" indicates that the object code (the address of the 
subroutine SPEAK) will be adjusted by the linker. 

THEN CALL KISSBABY 

This statement calls the subroutine KISSBABY, another unbound global. In the listing of this 
statement (line 00036), the memory location is 0003, since the previous instruction (CALL 
SPEAK) occupies bytes 0000-0002. 

LAST JMP NEXTBABY 

This statement is an 8080A assembly language instruction. The object code generated is 
"C30100". (See line 00037 in the assembler listing.) C3 is the OP code for the instruction 
JMP. NEXTBABY has the value 0001 (the 8080A stores two-byte numbers in low-byte/high- 
byte order). This value will be adjusted by the linker, depending on the address of the section 
KISSBABY. 

; DEFINE COMMON SECTION "SPEECH". 
This is another comment line. 

COMMON SPEECH, ABSOLUTE 
ORG 100H 

The assembler directive COMMON declares the next block of statements to be a new section 
of type COMMON. The name of the section is SPEECH and it is an absolute section. The 
location of the first byte of the section is defined to be 100H by the ORG statement. 

APPLAUSE BLOCK 80H 

This statement generates the first byte of the common section SPEECH. The memory location 
of the first byte is 0100H. 

00041 0100 0080 APPLAUSE BLOCK 80H 

memory location 

This BLOCK directive reserves a block of 80H bytes. The symbol APPLAUSE represents the 
address of the first byte of the block (0100). 
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MESSAGE EQU $ 

This statement is an assembler directive that assigns a value to the symbol MESSAGE. The 
dollar sign ($) in the operation field returns the value of the location counter. The assembler 
listing shows that the value 0180 was assigned to MESSAGE. 

00042 0180 MESSAGE EQU $ 

The location counter was advanced to 0180H when the directive "BLOCK 80H" was 
assembled. MESSAGE represents the address of the next byte of object code to be 
generated. 

PROMISE VOTERS, "WILL ALWAYS HAVE" 

This statement invokes the macro PROMISE, which was previously defined. There are two 
macro parameters: (1) the symbol VOTERS and (2) the character string "WILL ALWAYS 
HAVE". This single source line generates eight lines in the assembler listing: 



00043 



0180 20454E47 
0184 494E4545 
0188 52532057 
018C 494C4C20 
0190 414C5741 
0194 59532048 
0198 415645 



PROMISE VOTERS, "WILL ALWAYS HAVE" 
ASCII " ENGINEERS WILL ALWAYS HAVE" 



-text substitution indicator 



ASCII representation of " ENGINEERS WILL ALWAYS HAVE' 



When the macro is invoked, the assembler processes the lines of the macro definition. The 
assembler listing shows us only the one source line that generates object code, namely: 

ASCII " ENGINEERS WILL ALWAYS HAVE" 

Let's look at the other statements in the macro definition: 
SENTENCE SET "" 

This SET directive assigns the null string ("") to SENTENCE. 

PARAM SET 1 ; POINT TO FIRST PHRASE. 

This SET directive assigns the value 1 to the numeric variable PARAM. 





REPEAT 


PARAM <= •#• 




REPEAT 


SENTENCE 


SET 


SENTENCE:" ": 


'PARAM' 


FOR 


PARAM 


SET 
ENDR 


PARAM + 1 




EACH 
; PHRASE. 



This block of statements (a repeat block) is assembled repeatedly until the REPEAT operand 
(PARAM <= '#') is false. When a macro is assembled, the '#' is replaced with the number of 
parameters passed from the macro invocation. In this statement, the '#' is replaced with 2 
(two parameters), so the block of statements is repeated twice. (See "Determining Parameter 
Count" in the Macros section of this manual.) 
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The first time the block is assembled 'PARAM' is replaced with VOTERS, since PARAM has 
the value 1 and VOTERS is the first parameter. The second statement in the block 
concatenates the current value of the string variable SENTENCE (""), a space (" "), and the 
value of VOTERS ("ENGINEERS"); the resulting string is assigned to SENTENCE. SENTENCE 
now has the value of: 

" ENGINEERS" 

The next statement increments the current value of PARAM by one. PARAM now hoids the 
value 2. Since the repeat condition (PARAM <= '#') is still true, the block of statements is 
repeated. This time, 'PARAM' is replaced with "WILL ALWAYS HAVE", the second 
parameter. The statement concatenates the current value of SENTENCE (" ENGINEERS"), a 
space (" "), and the character string "WILL ALWAYS HAVE". SENTENCE now has the value 
of: 
" ENGINEERS WILL ALWAYS HAVE" 

PARAM is incremented to 3. The repeat condition is no longer true, so the assembly 
continues with the statement following the ENDR: 

ASCII "'SENTENCE'" 

This statement generates object code and is therefore listed in the assembler listing. The 
object code generated is the ASCII representation of each character of the string in the 
operand field. The assembler first makes the text substitution indicated by the single quotes 
("). "SENTENCE" is replaced with "ENGINEERS WILL ALWAYS HAVE". Notice that the text 
substitution is shown on the source listing, along with the text substitution indicator (+). 

Assembly continues with the statement following the macro invocation. 

PROMISE "A FRIEND IN", MYSELF,"." 

This statement invokes the macro PROMISE again. This invocation has three parameters: (1 ) 
the character string "A FRIEND IN", (2) the symbol MYSELF, and (3) the string ".". The 
resulting object code is the ASCII representation of " A FRIEND IN KEN DEDATE ." 

PROMISE "TELL YOUR FELLOW", VOTERS 

This next statement invokes the macro PROMISE with two parameters, the string "TELL 
YOUR FELLOW" and the symbol VOTERS. The resulting object code is the ASCII 
representation of: 

" TELL YOUR FELLOW ENGINEERS" 

The next statement in the sample program is: 

LIST ME ; SHOW FULL MACRO EXPANSION. 

The LIST directive turns on various features of the assembler listing. This statement sets the 
ME/MEG option to the ME setting: When a macro is invoked, the assembler listing shows all 
of the assembled statements of the macro expansion. (Comment lines within a macro are not 

laui v uoTii iniui i.; 
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PROMISE "TO VOTE FOR" .MYSELF," . " 

This macro invocation returns the ASCII representation of " TO VOTE FOR KEN DEDATE ." 
Notice in the assembler listing (following line 00047) that the text substitution indicator 
appears on seven lines. The '#' is replaced by "00003" and 'PARAM' is replaced by the 
appropriate parameter. 

Also notice in the assembler listing that a character is missing from the end of the line: 

+ SENTENCE SET SENTENCE:" ":"T0 VOTE FOR" ; FO 

In the source program, the comment was "; FOR". The "R" does not appear on the source 
listing because the LIST TRM directive had previously trimmed the listing to 72 characters. 

The last statement of the source code is: 
END 

This statement marks the end of the source program. 



Sample Symbol Table 

Now let's examine the symbol table for the sample program (Fig. 3-2, Sheet 3). Listed under 
Strings and Macros are four symbols: MYSELF, PROMISE, SENTENCE, and VOTERS. The 
"S" indicates that MYSELF, SENTENCE, and VOTERS are string variables. The "M" indicates 
that PROMISE is a macro. The number of bytes required to store the macro definition is 
0135H. 

Listed under Scalars are not only the numeric symbols used in the program (CONTRIB, 
PARAM, and SEATS), but also 8080A register names, since they are also symbols with 
scalar values. Each variable is listed with the last value assigned to it. 

"DELIBERA" is listed in this section of the table. The four stars (****) flag it as an undefined 
symbol. When the assembler examined the statement "DELIBERATE ERROR", the word was 
treated as an undefined symbol since it was not an assembly language instruction, an 
assembler directive, or a defined macro. (Only the first eight characters of a symbol are 
recognized.) This error also explains the next line of the symbol table: 

% (default) Section (0003) 

When there are statements in an undefined section, the assembler assigns them to the 
default section. (See the SECTION directive, in the Assembler Directives section of this 
manual, for a description of the default section.) In our sample' program, the assembler 
generated three bytes of zeros in response to the "DELIBERATE ERROR" line and created a 
default section. 
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There are four Sections in our program: the default section, CAMPAIGN, SEATING, and 
SPEECH. 

CAMPAIGN Section (0009) 

ELECTION 0008 E FIRST — 0000 LAST — 0006 

THEN — 0003 

In this section summary, the name of the section is CAMPAIGN, which is of type "Section". 
The section is 0009 bytes long. The addresses of the four symbols, ELECTION, FIRST, LAST, 
and THEN, are relative to the base address of the section and are subject to relocation, since 
the section is byte-relocatable. The "E" that follows the symbol "ELECTION" indicates that 
the ENDOF function is used to determine the value. 

Section SEATING is a "Reserve" section that is 01 F4 (hexadecimal) bytes long. Section 
SPEECH is a "Common" section that is not relocatable (absolute) and is 01 E8H bytes long, 
including the 100H-byte gap at the beginning of the section. 

In our sample program, the symbols KISSBABY and SPEAK are the only unbound globals. 

Let's look at the lines of statistics: 

48 Source Lines 108 Assembled Lines 47025 Bytes available 

2 ERRORS 1 UNDEFINED SYMBOLS 

There are more Assembled Lines (108) then Source Lines (48) because the macro 
invocations and REPEAT block cause some of the source lines to be assembled more than 
once. 

The statistics also include the number of Bytes Available in the assembler for further 
storage of labels, string variables, and macros. 

There are two Errors listed for this sample program: (1 ) the user-defined warning, and (2) the 
error generated by the line "DELIBERATE ERROR". "DELIBERA" is the Undefined Symbol. 
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Section 4 
LANGUAGE ELEMENTS 



INTRODUCTION 

This section provides reference information about the Tektronix Assembler language 
elements. The section discusses the following topics: 

• Statement Fields — Explains the four fields in an assembler source statement: label, 
operation, operand, and comment. 

• Symbols — Explains how symbols are used in assembler source programs. 

• Values — Describes numeric and string values used by the assembler. 

• Text Substitution — Describes the use of text substitution. 

• Expressions — Describes the type of permitted expressions, and their required formats. 
Describes the use of operators in expressions. Defines and gives the results of 
assembler functions. The functions are listed alphabetically for reference. 



STATEMENT FIELDS 

An assembly language source program consists of statements. Each statement occupies one 
line of text. Each statement may contain up to 127 characters; the line ends with a return 
character (ASCII code 13). Blank lines can be used within the program for readability and 
have no effect on the assembly. 



A statement consists of four fields. Each field may vary in width, and certain fields may be 
omitted, but the fields always occur in the following order: 



LABEL OPERATION OPERAND 



COMMENT 



Readability is improved when each field has a constant width on each line. This columnar 
format can be implemented with tab settings. Fig. 4-1 is an example of a formatted 8080A 
source file. 



Label 


Operation 
GLOBAL 


Operand 
PORTN, OUTSUB 


Continent 




PORTN 


EQU 


15 


; PORT = 15 




START 


MVI 


A "?" 


; CHARACTER = "?" 






CALL 


OUTSUB 


; SEND "?" TO PORT 15... 






HLT 




; ... AND STOP. 






END 


START 




3454-11 



Fig. 4-1. Formatted Source File. 



Each field has a constant width in this 8080A source program, making it easier to read. 



@ 
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Label Field 

The label field, when used, must begin in the first character position of a line. A space or tab 
terminates the label field. A statement's label allows the statement to be referenced by other 
statements. 

The label is a user-defined symbol. The symbol must follow the rules for constructing 
symbols (described later in this section). Embedded spaces are not permitted within a symbol. 
Every label must be unique within each assembler source program. The assembler generates 
an error message when duplicate labels are used. 



A label is permissible in all statements, including assembler directives, assembly language 
instructions, and macro invocations. 

The meaning of the label in an assembler directive statement depends upon the particular 
directive. For most directives the label is optional and not always meaningful. However, 
labels are always required with the EQU and SET directives. See the Assembler Directives 
section of this manual for the specific meaning in each directive. 

Label Operation Operand Comnent 
PORTN EQU 15 ; PORT = 15 

In this example, the constant symbol PORTN is given the value 15. 

A label used in an assembly language instruction or macro invocation represents the 
memory address of the first byte of the instruction. 

Label Operation Operand Comnent 
START MVI A,"?" ; CHARACTER = "?" 

In this line, the label START represents the address of the first byte of the MVI instruction. 



An address is relative to the base address (beginning address) of the section in which it 
appears. At link time, relocatable sections are assigned a new base address. Therefore, any 
symbol representing an address is relocated relative to its base address at link time. (See the 
Address Values discussion in this section for more information on relative addresses.) 
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Operation Field 

The operation field begins immediately after the label field. If the label is omitted, the 

nnQi-otinn -ficiiH maw Kanin antM/hara aftor tho tirct rharaptar r-i/->oiti/-\n in th>o iirta Tho 

operation field is terminated by a space, a tab, a return character, or a semicolon (indicating 
the beginning of a comment field). 

The word in the operation field indicates the type of action to be taken by the assembler. The 
word may be an assembly language instruction mnemonic, an assembler directive, or a 
macro invocation. 

If the word in the operation field is an assembly language instruction, the assembler 
translates the statement into a machine instruction. 



Label Operation Operand Comment 
START MVI A,"?" ,' CHARACTER = »?" 

MVI (an 8080A mnemonic) is translated into a machine instruction by the assembler. 

An assembler directive in the operation field specifies certain actions to be performed during 
assembly. Assembler directives may or may not generate object code. 

Label Operation Operand Comment 
GLOBAL P0RTN,0UTSUB 

In this example, the assembler directive GLOBAL in the operation field declares PORTN and 
OUTSUB as global symbols. 

NOTE 

The name of an assembly language instruction for a particular 
microprocessor may be identical to an assembler directive. In this case, the 
name of that assembler directive is changed. A list of any changed assembler 
directive names are found in the appropriate Assembler Specifics section for 
your microprocessor. 
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A macro name in the operation field specifies the macro definition block to be expanded. 

Label Operation Operand Corrment 

MACRO QQQ ; MACRO QQQ DEFINED 

ENDM 

QQQ ; INVOCATION OF MACRO QQQ 

In this example, the macro QQQ is invoked when QQQ appears in the operation field. 

If the operation field does not contain an assembly language instruction, an assembler 
directive, or a macro name, the assembler rejects the entire statement and prints an error 
message. See the Assembler Specifics section of this manual for a list of your processor's 
instruction mnemonics. Assembler directives are presented alphabetically in the Assembler 
Directives section of this manual. Macros are described in the Macros section of this manual. 



Operand Field 

The operand field specifies values required by the assembly language instruction, the 
assembler directive, or the macro invocation in the operation field. The word in the operation 
field determines the required type, number, and order of operands. For example: 

Label Operation Operand Corrment 

START MVI A,"?" ; CHARACTER = "?" 

The 8080A MVI instruction requires two operands: a register, followed by a value. In this 
example, register A (a predefined symbol) and a string value are used. 

The value in the operand field may be represented by an expression. (See the Expression 
discussion in this section.) An expression may consist of the following: 

• a numeric or string constant, 

• a symbol, or 

• a combination of constants and symbols with operators and functions. 

Symbols appearing in the operand field may be predefined or user-defined. (See the Symbols 
discussion in this section.) If a symbol appearing in the operand field is not predefined, it 
must be defined in one of the following ways: 

• the symbol must appear in the label field of an assembly language instruction, or of an 
ASCII, BLOCK, BYTE, EQU, SET, or WORD directive; or 

• the symbol must appear in the operand field of a GLOBAL, STRING, SECTION, 
COMMON, or RESERVE directive. 
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The operand field may contain spaces to improve program readability. The spaces must not 
be within symbols. 

lSuci upcrsoion uperanu 

BYTE 5,35,45,55 

BYTE 5, 35, 45, 55 

Both of the above statement lines produce identical results. 



Comment Field 

The comment field is optional, but may be included in any statement line. The comment field 
begins with a semicolon (;) and ends with a return. All characters following the semicolon 
are considered a part of the comment. Comments are used for program documentation and 
have no effect on the object code produced by the assembler. If no other fields are used, the 
comment field may begin anywhere in the statement line. 

Label Operation Operand Conment 

; SUBROUTINE OUTSUB — OUTPUTS A CHARACTER 

OUTSUB OUT PORTN ; OUTSUB STARTS HERE 

In this example, the first statement has no effect on the object code produced, because the 
semicolon (;) in the first column causes the entire line to be treated as a comment. In the 
next line, the semicolon causes "OUTSUB STARTS HERE" to be treated as a comment. 

Text substitution is the only type of action performed by the assembler within the comment 
field. Text substitution is discussed later in this section. The single quote (') signals 
substitution. Therefore, to include a single quote (') character within a comment, you must 
precede the ' character with an up-arrow (A) character. 

NOTE 

The up-arrow (A) character cancels the special significance of the 
immediately following character. 
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SYMBOLS 

A symbol is a user-defined or predefined word that represents a value or an instruction. 
Symbols make a program easier to read, and reduce the risk of error when the program is 
modified. 



User-defined Symbols 

A user-defined symbol is a word or mnemonic that you create to represent a numeric value 
(scalar or address), a string value, or a macro name. By using symbols you can refer to a data 
value or a memory address without using the specific value. 

For example, if you need to refer to a data value frequently within a program, that value can 
be assigned to a symbol. Then, if you need to change that value, you only need to modify the 
defining statement, rather than modify each statement that references the value. 

PORTN EOU 15 

In this statement the symbol PORTN is defined by the EQU directive to have the value of 15. 
PORTN can be used throughout the program. 



Constructing Symbols 

A symbol consists of one or more characters beginning with a letter and containing only 
letters, digits, periods, underscores, or dollar signs. Only the first eight characters are 
considered significant; any additional characters are discarded. Some examples of valid user- 
defined symbols are: 

PORTN 

OUTSUB 

LOOP 

LOOP. 5 

A 123456$ 

TO_DO 

AVERYLONGSYMBOL (same as AVERYLON) 

Defining Symbols 

User-defined symbols are defined when they appear in: (1) the label field of assembly 
lanugage instructions, macro invocations, and assembler directives, or (2) the operand field 
of GLOBAL, SECTION, COMMON, RESERVE, MACRO, or STRING directives. User-defined 
symbols are assigned values during the assembler's first pass. When the symbols are 
encountered in the second pass, they are replaced by the assigned values. 
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A symbol in the label field of an assembly language instruction represents the address of the 
first byte of that instruction. A label symbol allows you to transfer control to an instruction 
without knowing its absolute address. For example, a destination address for a jump 
instruction (JMP in 8080A) can be represented with a symbol. 

LOOP INC A 



JMP LOOP 

LOOP is a user-defined symbol representing the address of the instruction INC (Increment). 

When a symbol is used in the label field of an assembler directive, its meaning depends upon 
the directive. Generally, the symbol represents a data constant or the memory address of 
data. See the Assembler Directives section of this manual for the specific meaning in each 
directive. 

Generally, a symbol may not be redefined within a program. However, the SET directive may 
be used to redefine a symbol previously defined by the SET directive. This allows you to 
temporarily assign a value to an assembler variable during assembly. 

Predefined Symbols 

Predefined symbols include: 

• assembler directives and options, 

• assembly language instruction mnemonics, and 

• processor register names and symbols. 

The assembler directives and options are listed in the Assembler Directives section of this 
manual. See the Assembler Specifics section of this manual for the list of instruction 
mnemonics and reserved words for your processor. 

VALUES 

The assembler recognizes two kinds of values: numeric and string. 

Numeric Values 

The assembler uses two types of numeric values: scalars and addresses. All numeric values 
are treated as 16-bit (2-byte) numbers. Scalars are signed values. Addresses are unsigned 
values. 



Scalar Values 

Scalar values are signed integers ranging from -32768 to 32767. (The two's complement of 
a positive number represents the corresponding negative integer.) Scalar values can be used 
as numeric data within an assembly language program. 



& 
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Address Values 

An address value specifies a memory location. An unsigned 16-bit address takes a value in 
the range to 65535. 

An address is defined relative to the beginning of the section in which it appears. The 
assembler generates an object module (made up of one or more sections) with address 
values relative to the beginning of each section. At assembly time, the beginning (base 
address) of each relocatable section is zero. At link time, the linker relocates the individual 
sections. (See the Linker section of this manual for a discussion on section relocation.) The 
base address of each section is then redefined by the linker. The actual address of a byte is 
unknown until after the linking process is complete. 

During assembly, a location counter (which simulates the processor program counter) holds 
the address of the object code being generated. The dollar sign ($), when used in the operand 
field, represents the current value of the location counter (the address of the machine 
instruction or data item currently being generated). For example: 

Label Operation Operand 
IF $ > OFFH 

In this statement the current value of the location counter is compared with the value OFFH. 



Numeric Constants 

Numeric constants may be entered in decimal, binary, octal, or hexadecimal notation. The 
assembler assumes that a number is in decimal unless a suffix letter identifies it as binary, 
octal or hexadecimal. The following suffix letters are used: 

• B denotes binary numbers. 

1010B and 11111111B are binary numbers 

• O (capital letter O, not zero) or Q denotes octal numbers. 

377Q and 1777770 are octal numbers 

• H denotes hexadecimal numbers. 

1A2CH and OFFFFH are hexadecimal numbers. 



NOTE 

Numeric constants must begin with a numeric character. Any hexadecimal 
number that has an alphabetic character in the first digit must be preceded 
with a zero. 

A numeric constant may be assigned to a symbol with the EQU directive. 
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In this example, PORTN is made synonymous with the constant 15. 



Numeric Variables 

During assembly, a numeric value may be assigned to an assembler variable with the SET 

rlirortivo An aQQpmhlpr wariahlo alln\A/Q tpmnnrarv aQcinnmontc tn ho mar\e> in a cwmhnl 
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When the variable is encountered, the current value is used. Rules for creating an assembler 
variable follow the rules for creating a user-defined symbol. (See User-defined Symbols in 
this section.) A symbol used as an assembler variable must not have been previously defined. 



COUNT SET T 

In this example, the symbol COUNT is an assembler variable and may be assigned various 
numeric values with the SET directive. When the symbol COUNT is encountered by the 
assembler, the current value is used. If another SET directive reassigns another value to 
COUNT, the reassigned value is used. 



String Values 

Character strings are accepted by the assembler. Individual characters are translated into 
their ASCII representation (8 bits). 



String Constants 

String values entered as constants in an assembler program are enclosed in double quotes 

"STRINGS" 

The null string ("") contains zero characters. Any ASCII character, with the exception of the 
return character, may be included in a string constant. To include special characters, such as 
a double quote (") or a single quote ('), precede the special character with an up-arrow (A). 

NOTE 

The up-arrow character (A) cancels the special significance of the 
immediately following character. 
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String Variables 

A character string may be assigned to a string variable with the SET directive. The symbol to 
be used as the string variable must be declared with the STRING directive before being used. 
The STRING directive specifies the maximum length of the string variable. The maximum 
length (which defaults to 8) is enclosed in parentheses. For example: 

STRING STVAR (10) 

STVAR SET "CHARACTERS" 

In this example, the symbol STVAR is a string variable. The maximum length for any string 
assigned to the variable STVAR is ten. 

The length of the string variable is the length of the character string currently assigned to. the 
variable. If the length of the character string is longer than the declared length of the 
variable, the character string is truncated and an error message is generated. 

Conversions 

A string constant may be assigned to a symbol with the EQU directive. 

Label Operation Operand 
SYM1 EQU "AB" 

The string is converted to a two-byte numeric value. The numeric value is the ASCII 
representation of the string. If the string is longer than two characters, the first two 
characters are converted and an error message is generated. If the string length is one 
character, the high-order byte of the resulting value is zero. The value of the null string ("") is 
zero. For example: 



Character String 


Numeric Value 


tut 


0000H 


"A" 


0041 H 


•'■}•• 


003 FH 


"AB" 


4142H 


"ABC" 


4142H (error message 085 is generated) 


"12" 


3132H 



For an ASCII-to-hexadecimal conversion table, see the Tables section of this manual. 

If a numeric value is assigned to a string variable, the numeric value is converted to its string 
representation. The string representation is six characters long. The first character is a zero 
or minus (-) depending on the sign of the number. The remaining five characters are the 
decimal representation of the value, padded with leading zeros (if necessary). The following 
table shows how values are converted to their string representation. 
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Text Substitution 



Value 


String 




-1 

400 
200H 


"000000" 
"-00001 " 
"000400" 
"000512" 



For example: 

STRING 
STRVAR SET 



STRVAR (10) 
-1 



STRVAR now has the value "-00001 



TEXT SUBSTITUTION 

String values can be substituted within a statement line during assembly by the use of string 
variables. The single quote (') is the substitution delimiter. When the assembler encounters a 
string variable enclosed within single quotes ('variable'), the variable is replaced by the 
current string value assigned to that string variable. 

When processing a statement, the assembler first performs all indicated text substitutions. 
For example: 

Label Operation Operand Comment 



OP 



STRING 
SET 



OP 
"WORD" 



'OP' 1,2,3 ; DO 'OP' TO 1,2,3 

When the assembler scans the line "'OP' 1,2,3", it first performs the following substitution: 

WORD 1,2,3 ; DO WORD TO 1,2,3 

The statement line then contains the assembler directive WORD. 

During assembly, the percent sign (%) represents the current section name. With the use of 
text substitution, the current section name can be inserted into the assembly language 
program. For example: 

Label Operation Operand Comment 

STRING SECNAME(8) 
SECNAME SET "'%•" ; SAVE CURRENT SECTION NAME 
SECTION QQ ; SWITCH TO NEW SECTION 



RESUME 



•SECNAME' ; SWITCH BACK TO PREVIOUS SECTION 



Parameter substitution performed during macro expansion is a form of text substitution. See 
the Macros section for information on parameters. 
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EXPRESSIONS 

Introduction 

An expression is a combination of constants, variables, or functions connected by operators 
that yields a numeric or string value. The assembler accepts expressions in the operand field. 
An operand expression is evaluated at assembly time, and the numeric or string value is 
used. Table 4-1 lists the operators and functions that can be used in expressions. 

Table 4-1 
Expression Operators and Functions 



Type 


Operator/ Function 


Meaning 


Unary Arithmetic 


+ 


Identity 




" 


Sign inversion 


Binary Arithmetic 


* 


Multiplication 




/ 


Division 




+ 


Addition 




- 


Subtraction 




MOD 


Remainder 




SHL 


Left shift 




SHR 


Right shift 


Unary Logical 


\ 


NOT (bit inversion) 


Binary Logical 


& 

! 


AND 
Inclusive OR 




M 


Exclusive OR 


Relational 


- 


Equal 




< > 


Not equal 




> 


Greater than 




>= 


Greater than or equal 




< 


Less than 




<= 


Less than or equal 


String 




Concatenation 


Logical Functions 


BASE 


Base address comparison 




DEF 


Symbol definition 


Numeric Functions 


ENDOF 


End of section 




HI 


High byte 




LO 


Low byte 




SCALAR 


Conversion to scalar 


String Functions 


NCHR 


Number of characters 




SEG 


Substring 




STRING 


Conversion to string 
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Operators 
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!n an expression involving more than one operator, the operators are performed according to 
a predefined order of precedence. Tabie 4-2 shows the operator hierarchy. 

Table 4-2 
Hierarchy of Operators 



Precedence 


Operators 


1. 


BASE DEF ENDOF HI LO NCHR SCALAR SEG STRING (functions) 


2. 


: (concatenation) 


3. 


+ - (unary plus and minus) \ (logical NOT) 


4. 


* / MOD SHL SHR (multiplication, division, shifts) 


5. 


+ - (addition, subtraction) 


6. 


= <>>>=<<= (relational) 


7. 


& (logical AND) 


8. 


! !! (logical OR, exclusive OR) 



Expression operators at the top of the table have the highest precedence and are performed 
first. Operators at the bottom have the lowest precedence and are performed last. Operators 
on the same line have equal precedence, and are performed from left to right within the 
expression. 

Parentheses may be used to override the order of precedence. The most deeply nested 
subexpressions are evaluated first. It is possible to create an expression that is too complex 
for the assembler to evaluate. If the expression entered is too complex, an expression error 
message is displayed. 



Operators 

An operator within an expression acts upon one or more terms. The operators and types of 
terms permitted for each operator are discussed in the following paragraphs. 

If an operator requires a numeric operand and a string operand is provided, the string 
operand is converted to a numeric value, as described in String Conversions (earlier in this 
section). 
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Arithmetic Operators 

Arithmetic operators act on numeric values. 



+ Unary plus 

Unary negative 

* Multiplication 
/ Division 
+ Addition 



Subtraction 



Identity operator: does not change the value of the term. May be 
applied to scalar or address values. 

Indicates sign inversion. (Two's complement.) May be applied to 
scalar values only. 

Multiplies two scalar values. 

Divides two scalar values. 

Adds two terms (scalar or address), as follows: 

Scalar + Scalar = Scalar 
Scalar + Address = Address 
Address + Scalar = Address 
Address + Address = error 

Subtracts two terms (scalar or address), as follows: 
Scalar - Scalar = Scalar 
Address - Scalar = Address 

Address - Address = Scalar (addresses must have same base) 
Scalar - Address = error 



MOD Remainder 



The remainder that results from dividing the first term by the 
second. The sign of the returned value is determined by the sign of 
the second term. For example: 



X 


Y 


X MOD Y 


2 


2 





5 


2 


1 


5 


-2 


-1 


-5 


2 


1 


-5 


-2 


-1 
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Operators 



SHL Left shift 



The first term is shifted to the left the number of bit positions 
specified by the second term. Both terms must be scalar values. 
The second term (the number of bits to be shifted) must be a non- 
negative scalar value. For example: 

1 SHL 1 results in 2 
















































1 


































1 

| 








1 
1 jo 



When the bits are shifted, the leftmost bits are discarded; the 
vacated bit positions on the right become zeros. For example: 

OFOFOH SHL 1 results in 0E1E0H 



1 


1 


1 


1 














1 


1 


1 


1 
















1 


1 


1 














1 


1 


1 


1 


















SHR Right shift 



If the second term is greater than 16, the result is zero, and an 
error message is generated. 

The first term is shifted to the right the number of bit positions 
specified by the second term. Both terms must be scalar values. 
The second term (the number of bits to be shifted) must be a non- 
negative scalar value. For example: 

2 SHR 1 results in 1 













































1 




















































1 



When the bits are shifted, the rightmost bits are discarded; the 
vacated bit positions on the left become zeros. If the second term is 
greater than 16, the result is zero, and an error message is 
generated. 
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Logical Operators 

The logical operators, NOT (\), AND (&), OR (!), and exclusive-OR (!!), correspond to their 
Boolean algebra equivalents, as shown in the following truth table. 



X 


Y 


\x 


X&Y 


X!Y 


X!!Y 








1 














1 


1 





1 


1 


1 











1 


1 


1 


1 





1 


1 






\ NOT 



Returns the one's complement of the following term by complementing 
each bit in the term. (Returns a 1 if the bit is 0, and returns a if the bit 
is 1.) 

\0F0FH results in 0F0F0H 















1 


1 


1 


1 














1 


1 


1 


1 




1 


1 


1 


1 














1 


1 


1 


1 















& AND 



Returns the logical AND of two terms. Compares the terms bit-by-bit, 
returning a 1 if both bits are 1; otherwise returns a 0. 



Example: 

DVAL EQU 



0F0F0H & OCCCOH 



1 


i 


i 


i 














1 


1 


1 


i 














1 





1 





1 





1 





1 





1 

















DVAL is assigned 0C0C0H 


1 





1 

















1 





1 


















! OR 



Returns the logical OR of two terms. Compares terms bit-by-bit; returns 
a 1 if either bit is 1, returns a if both bits are 0. 



Example: 
RVAL EQU 



0F0F0H ! OCCCOH 



1 


1 


1 


1 














1 


1 


1 


1 














1 





1 





1 





1 





1 





1 











0. 





RVAL is assigned OFCFOH 


1 


1 


1 


1 


1 





1 





1 1 1 


1 


1 
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Operators 
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bit and returns a 1 when the bits are different, and a when the bits are 



Example: 

ERVAL EQU 



OFOFOH !! OCCCOH 



1 


1 


1 


1 














i 


1 


1 


1 














1 





1 





1 





1 





1 





1 

















ERVAL is assigned 5A50H 





1 





1 


1 





i 








1 





1 















Relational Operators 

Relational operators compare two terms and return the value -1 for a true expression and 
for a false expression. 

= Equal 

<> Not equal 

> Greater than 

>= Greater than or equal 

< Less than 

<= Less than or equal 

Relational operators allow comparison of scalar values, address values, and string values. 

Scalar values are compared as signed numeric values. For example: 

Label Operation Operand 



COUNT SET 

IF 
IF 



COUNT < 5 
COUNT > -1 



EQU 



7 = COUNT 



The relational operators in this example compare signed numeric (scalar) values. 
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Address values are compared as unsigned numeric values. Address values are compared as 
offsets from their base address. Address values from different sections cannot be compared. 

START MVI A,"?" 



NEXT MVI 
T EQU 



H,0000 
START < NEXT 



The less than (<) operator in this example compares two unsigned numeric (address) values 
within the same section. 

If only one term is an address, a relational operator performs an unsigned numeric 
comparison between the scalar and the address offset. 



String values are compared numerically according to the ASCII collating sequence. (See the 
Tables section of this manual.) Comparison proceeds left to right, character-by-character. 
Two strings are considered equal if they have the same length and contain identical 
character sequences. If they are identical in sequence but one string is longer than the other, 
the longer string is considered greater. The following examples show the results of various 
string comparisons: 



"AB" = "AB" results in 

"A" > "B" results in 

"ABC" > "ABC " results in 

"ACB" > "ABC" results in 



-1 (true) 

(false) A less than B 

(false) the right term is longer 

-1 (true) C greater than B 



If only one term is a string, the first two characters of the string are converted to a scalar 
value and a numeric comparison is performed. 

The types of comparisons are summarized in Table 4-3. 



Table 4-3 
Types of Comparisons with Relational Operators 



Left Operand 


Right Operand 


String 


Scalar 


Address 


STRING 


String 
Comparison 


Signed Numeric 
Comparison 


Unsigned Numeric 
Comparison 


SCALAR 


Signed Numeric 
Comparison 


Signed Numeric 
Comparison 


Unsigned Numeric 
Comparison 


ADDRESS 


Unsigned Numeric 
Comparison 


Unsigned Numeric 
Comparison 


Unsigned Numeric 
Comparison 
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Functions 



String Operator 

Concatenation 



Combines two strings into a single string. For example: 

Label Operation Operand 





STRING 


STR1(5),STR2(6),STR3(1D 


STR1 


SET 


"HELLO" 


STR2 


SET 


" THERE" 


STR3 


SET 


STR1 : STR2 



STR3 now is "HELLO THERE". 

If the resulting string is assigned to a variable, the length of the 
resulting string must not exceed the length specified for that variable by 
the STRING directive. 

Numeric values may not be concatenated. 



Functions 

The following predefined functions return a value when used in an expression: 

• Logical Functions 

BASE — Determines whether two values have a common base. 
DEF — Determines if a symbol has been defined. 

• Numeric Functions 

ENDOF — Returns the address of the last byte of a section. 

HI — Returns the high byte of an address. 

LO — Returns the low byte of an address. 

SCALAR — Converts an address value to a scalar value. 



String Functions 

NCHR — Returns the current length of a string variable. 
SEG — Returns a substring of a string. 
STRING — Converts a scalar value to a string. 



Each of these functions is described in detail in the following pages. The same conventions 
as described in the Assembler Introduction section of this manual are used in these 
descriptions. 
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Determines whether two values have common base 



SYNTAX 
BASE(numvalue1 ,numvalue2) 



PARAMETERS 



numvalue Any expression that evaluates to a numeric value. Usually a label 

symbol. 



EXPLANATION 



The BASE function compares two numeric values to see if they have the same base. The 
BASE function returns a -1 (true) if the values have the same base. The BASE function 
returns a (false) if the values do not have the same base. 

All addresses within a section share the same base. All scalar values share the same base. 
Scalar values and address values do not have the same base. Each SECTION, COMMON, and 
RESERVE directive defines a new address base. The default section (any statements not 
preceded by a SECTION or COMMON directive) has a separate base. All unbound globals are 
assumed to have unique bases. 

The BASE function is typically used to compare label symbols in a conditional assembly 
statement. 



EXAMPLES 



Label Operation Operand 
Q EQU 5 



EQU 15 

IF BASE(Q,R) 



ENDIF 



both scalars 



Statements assembled 
because Q and R share 
common base 



In this example, the two scalar values Q and R are compared. Since both Q and R represent 
scalar values, they share a common base. The function BASE(Q,R) returns a -1 (true) and the 
statement lines between IF and ENDIF are assembled. 
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Function: BASE 

Determines whether two values have common base 



T —1-— 1 

LclUCl 


Operation 


Operand 




SECTION 


SEC1 


HERE 


BLOCK 


100H 


THERE 


BLOCK 


100H 




IF 


BASE (HERE, THERE) 



Statements assembled 
because HERE and THERE 
are in the same section 



ENDIF 



In this example, the statements between IF and ENDIF are assembled because HERE and 
THERE share the same base. 

Label Operation Operand 



SECTION 


SEC2 


HERE BLOCK 


100H 


COMMON 


WKSPACE 


THERE BLOCK 


100H 



IF 



ENDIF 



BASE (HERE, THERE) 



Not assembled 

because HERE and THERE 

not in same section 



In this example, the statements between IF and ENDIF are not assembled because HERE and 
THERE do not share the same base. 



Label Operation Operand 
THERE BLOCK 100H 



IF 



ENDIF 



BASE ($, THERE) 



Only assembled if 
THERE is in the 
current section 



In this example, the statements between IF and ENDIF are assembled if THERE is in the 
current section. The dollar sign ($) represents the current value of the location counter. 
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SYNTAX 



DEF(symbol) 



PARAMETERS 



symbol 



Any user-defined symbol. 



EXPLANATION 



The DEF function tests whether a symbol has been defined during the current assembler 
pass. (See the Assembler Introduction section of this manual for a description of the two 
passes of the assembler.) A value of -1 (true) is returned if the symbol is defined. A value of 
(false) is returned if the symbol is not defined. 



EXAMPLES 

Label Operation Operand 
; Q EQU 



IF 


DEF(Q) 


WORD 


15 


BYTE 


5 


ENDIF 





In this example, the semi-colon (;) in the first line flags the line as a comment and the line is 
not assembled. Therefore, the statements after the IF directive are not assembled, since Q 
has not been defined in the current assembler pass. If the semicolon is removed, the IF 
condition becomes true and the statements are assembled. 
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Function: ENDOF 

Returns end address of section 



SYNTAX 



ENDOF(section-name) 



PARAMETERS 



section-name The name of a section defined in the assembler source program. 



EXPLANATION 



The ENDOF function returns the address of the last byte of a section. The linker may relocate 
the individual sections during linking. Therefore, the ENDOF function is evaluated at link 
time. (The Linker section of this manual discusses how sections are relocated.) Further 
arithmetic operations may not be performed on the result of an ENDOF function. 



EXAMPLES 



Label Operation Operand 



RESERVE 

LXI 



STACK, 100 

SP, ENDOF (STACK) 



This 8080A example reserves 100 bytes for the stack (STACK) and loads the stack pointer 
register (SP) with the address of the end of the stack. The stack pointer register holds the 
address of the high byte of memory reserved for STACK. 
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SYNTAX 



Hl(numeric-expression) 



PARAMETERS 



numeric-expression Any expression that returns a numeric value, either scalar or address. 



EXPLANATION 



The HI function returns the most significant byte of a numeric expression. The result is a 
one-byte numeric value. The numeric expression may be either an address or a scalar value. 
If the expression is an address, further operations may not be performed on the result. 



EXAMPLES 



Label Operation Operand 



SECTION 

BLOCK 

BLOCK 

SECTION 

MVI 



TABLE, IN PAGE 

50 

50 

MAIN 

H, HI (TABLE) 



MVI 
MOV 
MVI 
MOV 



L,L0(Q) 
A,M 

L,L0(R) 
M,A 



In this 8080A example, the high byte of the beginning address of the section TABLE is loaded 
into the H register. Both Q and R will have the same high byte because INPAGE defines the 
section to be within one page. (See the Assembler Directives section for more information on 
the INPAGE relocation-option for sections.) The low byte of the addresses for Q and R is 
loaded into the L register. Data can be transferred without changing the H register. 
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Function: LO 

Returns low byte of numeric value 



SYNTAX 



LO(numeric-expression) 



PARAMETERS 



numeric-expression 



Any expression that results in a numeric value, either scalar or 
address. 



EXPLANATION 



The LO function returns the least significant byte of a numeric expression. The result is a 
one-byte numeric value. The numeric expression may be either an address or a scalar value. 
If the expression is an address, further operations may not be performed on the result. 



EXAMPLES 



See the HI function example. 
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NCHR(string-expression) 



SYNTAX 



PARAMETERS 



string-expression Any expression that returns a string. 



EXPLANATION 



The NCHR function returns the current number of characters in the specified string. The 
result is a numeric value. 

NOTE 

The current length of a character string is not necessarily the same as the 
maximum length of a string symbol as declared with the STRING directive. 
See the Assembler Directives section of this manual for information on the 
STRING directive. 



EXAMPLES 



The following example shows one use of the NCHR function within a macro repeat block: 

Label Operation Operand 





STRING 


STR (5) 


STR 


SET 


"HELLO" 


Q 


SET 


1 




REPEAT 


Q <= NCHR (STR) 




ASCII 


SEG(STR,Q,D," " 


Q 


SET 
ENDR 


Q + 1 



The repeat loop is repeated for Q = 1, 2, 3, 4, and 5. When Q = 6, the REPEAT condition is 
false and the assembly continues with the statement following ENDR. The ASCII 
respresentation of the individual characters "HELLO" are stored in consecutive bytes. 
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Function: SCALAR 

Converts address to scalar 



SYNTAX 



3UMi_Mi-i(aaaressj 



PARAMETERS 



address 



Any expression that returns an address value. 



EXPLANATION 



The SCALAR function converts an address (unsigned numeric) value into a scalar (signed 
numeric) value. 

The only arithmetic operations that can be performed directly on address values are: addition 
with a scalar value, and subtraction. To perform any other operations on address values, you 
must first convert the addresses to scalar values with the SCALAR function. 



EXAMPLES 



Label Operation Operand 

TABLE BLOCK 100 

XXX EQU SCALAR (TABLE) / 2 + TABLE 



This example shows an arithemetic operation (division by 2) performed on an address value. 
The address value is converted to a scalar value by the SCALAR function. 
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SYNTAX 



SEG(string, start-position, char-count) 



PARAMETERS 

string Any expression that returns a character string. 

start-position A numeric expression that indicates the position in the string of the first 

character of the substring. 

char-count Any numeric expression that evaluates to the number of characters to 

be returned. 

EXPLANATION 

The SEG function returns a substring of a character string. The first character in the 
substring is the character in the start- position. Each successive character is included until 
char-count characters are included or the end of the string is encountered. 

The following table shows various substrings returned by the SEG function: 



Expression 


Substring 


SEG("ABCDE",2,2) 
SEG("ABCDE",4,3) 
SEG("ABCDE",6,1) 
SEG("ABCDE",1,6) 


"BC" 
"DE" 

rrtt 

"ABCDE" 



EXAMPLES 



Label Operation Operand 



STRING 
STR SET 
LST SET 



STRC12), LST(1) 

"CHARACTERS" 

SEG(STR,NCHR(STR),1) 



L 



number of characters 
to be returned 



_ first character of substring 
(NCHR function returns the 
number of characters in STR) 
— character string 



Although the character string STR has a maximum length of 12, NCHR(STR) returns the 
current length which is 10. The start-position of the substring is the tenth character. The 
char-count is 1. Thus, the tenth character "S" is assigned to the string variable LST. 
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Function: STRING 

Converts scalar to string 



SYNTAX 



STRING(scalar) 



PARAMETERS 



scalar 



Any expression that evaluates to a scalar value. 



EXPLANATION 



The STRING function converts a scalar value to its string representation. The string 
representation is six characters long. The first character is a zero or minus (-) depending on 
the sign of the number. The remaining five characters are the decimal representation of the 
value, padded with leading zeros (if necessary). The following table shows how values are 
converted to their string representation. 



Value 


String 





"000000" 


-1 


"-00001 " 


400 


"000400" 


200H 


"000512" 



EXAMPLES 



Label Operation Operand 



STRING 
XVAL SET 
YVAL SET 



MATSIZE (6), DIGIT4C1) 

4 

50 



MATSIZE SET 
DIGIT4 SET 



STRING (XVAL * YVAL) 
SEG(MATSIZE,4,1) 



This example converts the value of XVAL times YVAL (4 * 50 = 200) to the string "000200' 
DIGIT4 is defined to be the fourth character in the string MATSIZE ("2") 
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Section 5 
ASSEMBLER DIRECTIVES 



ASSEMBLER DIRECTIVE INDEX 

Page 

Listing Control Directives 

LIST — Turns on listing options 5-23 

NOLIST— Turns off listing options 5-29 

PAGE— Skips to a new page in the listing 5-33 

SPACE— Inserts blank lines into the listing 5-45 

STITLE— Creates a listing page subtitle 5-46 

TiTLE — Creates a listing page title 5-49 
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Section 5 
ASSEMBLER DIRECTIVES 



INTRODUCTION 

This section describes the directives you may use when programming for the Tektronix 
Assembler. The directives are arranged in alphabetical order for easy reference. A functional 
index appears at the front of this section to help you when you do not know a directive by 
name. 

Each assembler directive description consists of the following parts: a syntax biock, 
parameter definitions, an explanation of the use and limits of the directive, and one or more 
examples of its use. 

The syntax block shows the required format of the directive. Assembler directive statements 
may contain information in any of the four fields: label, operation, operand, and comment. 
Since the comment field is strictly optional for any directive, it does not appear in the syntax 
block. 

The syntax blocks in this section use the notation conventions explained in the Assembler 
Introduction section of this manual. 



Label Operation Operand 

[symbol] DIRECT string-expression[, string-expression]... 



The above example shows the syntax for DIRECT, a fictional directive. You may interpret this 
syntax block as follows: 

• A label is optional for this directive. 

• The operation field must contain the word "DIRECT". 

• The operand field must contain at least one string expression. If two or more string 
expressions are entered, they must be separated by commas. The number of string 
expressions is limited only by the maximum line length (127 characters). 
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LABELS 

For each assembler directive, a label may be required, optional, or prohibited, depending on 
the directive. 

• Only the EQU and SET directives require labels. EQU and SET each assign the value in 
the operand field to the symbol in the label field. 

• Only the ENDM directive must not have a label. 

• The following directives generate object code and therefore often have labels. The label 
is assigned the address of the first byte of code generated. 

ASCII BLOCK BYTE WORD 

• The following directives affect the location counter but do not generate object code/so 
they do not normally have labels. The value assigned to the label depends on the 
directive. 

COMMON ORG RESERVE RESUME SECTION 

• All other directives (listed below) do not even affect the location counter and so do not 
normally have labels. The label, if any, takes the current value of the location counter. 
In the dictionary entry for each of these directives, the label is shown as optional but is 
not discussed as a parameter. 

ELSE EXITM LIST PAGE STRING 

END GLOBAL MACRO REPEAT TITLE 

ENDIF IF NAME SPACE WARNING 

ENDR INCLUDE NOLIST STITLE 
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ASCII 

Generates ASCII data 







SYNTAX 


Label 


Operation 


Operand 


[symbol] 


ASCII 


string-expression[, string-expression]. . . 



PARAMETERS 



symbol 



A user-defined label representing the address of the first character in 
the string. 



string-expression Any expression that yields a string value. 



EXPLANATION 



The ASCII directive stores the ASCII codes for the characters of the specified string(s) in 
consecutive bytes of the object program. Refer to the Tables section of this manual for an 
ASCII conversion table. 



EXAMPLES 



Label 
CHESSMEN 



Operation Operand 



ASCII 
ASCII 



"PAWN ROOK KNIGHT" 
"BISHOP", "QUEEN ","KING 



These two statements generate 36 consecutive bytes of ASCII code: one 18-character string 
and three 6-character strings, stored as a single 36-character sequence. CHESSMEN is the 
address of the first character from the first string. The following hexadecimal object code is 
generated: 

source: PAWN ROOK KNIGHT 

object: 50 41 57 4E 20 20 52 4F 4F 4B 20 20 4B 4E 49 47 48 54 

source: BISHOPQUEEN KING 

object: 42 49 53 48 4F 50 51 55 45 45 4E 20 4B 49 4E 47 20 20 
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SYNTAX 


Label 


Operation 


Operand 




[symbol] 


BLOCK 


byte-count 





PARAMETERS 



symbol 



A user-defined label that represents the address of the first byte of the 
block. 



byte-count 



The number of bytes to be reserved: any positive scalar expression. 



EXPLANATION 



The BLOCK directive reserves a specified number of bytes. BLOCK is used primarily to 
allocate memory for data that may change during program execution. 

The byte-count expression must yield a positive scalar value. Every symbol in the expression 
must have been defined previously. 



EXAMPLES 



Label 



Operation Operand 



LASTNAME 


BLOCK 


20 


SSN 


BLOCK 


11 


AGE 


BLOCK 


1 


SALARY 


BLOCK 


2 



These statements allocate space for a 20-character name, an 11 -character social security 
number, an age in the range to 255, and a salary in the range to 65535. 
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BYTE 



Generates byte(s) of data 







SYNTAX 


Label 


Operation 


Operand 


[symbol] 


BYTE 


byte-value[, byte- value]... 



PARAMETERS 



symbol 



A user-defined label that represents the address of the first byte of data. 



byte-value 



Any expression that yields a scalar in the range -128 to 255. 



EXPLANATION 



The BYTE directive stores the specified values in consecutive bytes of the object program. If a 
value is outside the range -1 28 to 255, it is truncated to 8 bits and the following message is 
displayed: 

***** ERROR 035: Value truncated to byte 



EXAMPLES 



Label Operation Operand 

MONTHS BYTE 31,28,31,30,31,3° 
BYTE 31,31,30,31,30,31 

Twelve bytes of object code are generated. The Nth byte contains the number of days in the 
Nth month. MONTHS is the address of the first byte. 



(a) 
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SYNTAX 


Label 


Operation 


Operand 


[symbol] 


COMMON 


section-name[, relocation-type] 



PARAMETERS 



symbol 

section-name 
relocation-type 



A user-defined label (usually omitted) that represents the address of the 
first byte of the common section. 

The name assigned to the section. 

An option to direct the relocation of the section at link time. You may 
specify one of the following relocation types: 

PAGE — The common section is relocated to the beginning of a page of 
memory. See the Assembler Specifics section of this manual for the 
page size for your microprocessor. 

INPAGE — The common section may be relocated to any address, so 
long as the entire section lies within one page of memory. 

ABSOLUTE — The section is not relocated. 

If you do not specify PAGE, INPAGE, or ABSOLUTE, the relocation type 
defaults to byte-relocatable: the relocated common section may begin at 
any byte in memory. 



EXPLANATION 



The COMMON directive declares a section of type COMMON and defines the name and 
relocation type of the section. The contents of the section are defined by the statements 
following the COMMON directive, up to the next SECTION, COMMON, RESERVE, or 
RESUME directive. 

Different source modules may declare the same common section, and thus share the 
contents of that section. (See Example 1.) The relocation type of the section must be the 
same in every module in which the section is declared. 

The linker assigns the same starting address to all common sections with the same name. 
Memory is allocated for the largest section with that name. (See Example 2.) 

You may use the directives ASCII, BYTE, or WORD to initialize values in a common section. 
(See Example 3.) If two or more modules specify values for the same location in a common 
section, the module linked last takes precedence; neither the linker nor the LOAD command 
flags the error. 
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COMMON 

Declares common section 



The name of a common section is a n !oba! symbol whose value is the address of the first byte 
of the section. A section name should not be declared with a GLOBAL directive in any 

r-r-i nri i i i q in lA/hir-hi tho cortinn ic ri'otinorJ \A/ith a fT^i\/i i\/if*iM Hirootiwa 



EXAMPLES 



COMMON Example 1 

This example illustrates how program modules can communicate with each other through 
values stored in a common section. 

Assume that source modules A, B, and C each contain the following common section 
definition: 
Label Operation Operand 

COMMON CUSTOMER 

CNAME BLOCK 30 

ADDRESS BLOCK 30 

CITY BLOCK 16 

STATE BLOCK 2 

During program execution, module A might define the customer's name, module B might 
define the address, and module C might define the city and state. All 78 bytes of customer 
information in the common section may be used or changed by any of the three modules. 



O 
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COMMON 

Declares common section 
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COMMON Example 2 

A common section may also be used as a scratch area. Some subroutines use blocks of 
memory for temporary storage. If all modules use the same common section for temporary 
storage, less memory is required than if each module uses a different block of memory. 

This example illustrates: 

• how a common section may be used as a scratch area by one or more modules; and 

• how the linker treats common sections with the same name but different lengths. 

In source module A, the following statements define common section SCRATCH: 
Label Operation Operand 





COMMON 


SCRATCH 


X1 


BLOCK 


4 


X2 


BLOCK 


6 



In source module B, SCRATCH is defined as follows: 





COMMON 


SCRATCH 


Y1 


BLOCK 


5 


Y2 


BLOCK 


10 



At link time, one area of memory is allocated to section SCRATCH. The size of the area is 1 5 
bytes, which is the length of the larger section named SCRATCH. Both subroutines may use 
this area of memory. 



c 


X1 


1 


Y1 


^ 


A 


2 


1 


bytes \ 


3 


» 5 

/ bytes 


I. 


4 






r 


X2 


5 


J 






6 


Y2 


s 

) 




6 ( 

bytes ^ 




7 






8 






9 






L 


10 


\ 10 
/ bytes 






11 




12 






13 






14 






15 
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COMMON 

Declares common section 



COMMON Example 3 

This example demonstrates how you may initialize data in a common section. 

Source module A defines common section CALENDAR and provides text for array DAYS: 
Label Operation Operand 

COMMON CALENDAR 
MONTHS BLOCK 36 

r\«vo *o/-tt ll c? tmiyiAHTiirurrMi 

ASCII "THUFRISAT" 



Source module B also defines CALENDAR and provides text for array MONTHS: 



MONTHS 



DAYS 



COMMON 


CALENDAR 


ASCII 


"JANFEBMARAPR" 


ASCII 


"MAYJUNJULAUG" 


ASCII 


"SEPOCTNOVDEC" 


BLOCK 


21 



A and B both specify the same length for common section CALENDAR (57 bytes). 
When the section is loaded into memory, its contents will be as follows: 



bytes source: JANFEBMARAPRMAYJUN 

1-18 object: 4A 41 4E 46 45 42 4D 41 52 41 50 52 4D 41 59 4A 55 4E 

bytes source: JULAUGSEPOCTNOVDEC 

19-36 OD ject: 4A 55 4C 41 55 47 53 45 50 4F 43 54 4E 4F 56 44 45 43 

bytes source: SUNMONTUEWEDTHUFR I 

37-54 object: 53 55 4E 4D 4F 4E 54 55 45 57 45 44 54 48 55 46 52 49 



bytes source: SAT 
55-57 object: 53 41 54 



MONTHS 



DAYS 



(a) 
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SYNTAX 



Label Operation 

[symbol] ELSE 



Operand 



EXPLANATION 



The ELSE directive separates the branches of an IF...ELSE...ENDIF block. 

If the conditional expression in the IF directive is nonzero (true), the statements between the 
IF directive and the ELSE directive are assembled. Otherwise, the statements between the 
ELSE directive and the ENDIF directive are assembled. 



EXAMPLES 



Label Operation Operand Comment 



NDAYS 
NDAYS 



IF 

EQU 

ELSE 

EQU 

ENDIF 



YEAR MOD 4 = 

366 ; LEAP YEAR 



365 



NOT LEAP YEAR 



Assembled if YEAR is 
divisible by 4. 

Assembled if YEAR is 

not divisible by 4. 



If the value of YEAR is evenly divisible by 4, the first EQU directive is assembled and the 
symbol NDAYS is assigned the value 366. Otherwise the second EQU directive is assembled 
and NDAYS takes the value 365. 
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END 



Ends source module 







SYNTAX 


Labei 


Operation 


Operand 


[symbol] 


END 


[transfer-address] 



PARAMETERS 



transfer-address The address of the first instruction to be executed. 



EXPLANATION 



The END directive marks the end of the source module, if the source module contains no 
END directive, assembly continues to the end of the last source file named in the ASM 
command line. 

The transfer address, if present, is the address of the first instruction to be executed when 
the program is run. The transfer address is usually specified in a source module, often in the 
module that contains the main program. However, the transfer address can also be defined 
or changed at link time. (See the TRANSFER command in the Linker section of this manual.) 
If more than one module contains a transfer address, the transfer address in the first module 
linked is used. 



EXAMPLES 

Label Operation Operand 
START XRA A 



END 



START 



In this example, END is the last statement in the main program source module. START is the 
transfer address: program execution starts with the 8080A instruction XRA A. 



(ft 
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Ends IF block 
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SYNTAX 


Label 


Operation 


Operand 




[symbol] 


ENDIF 







EXPLANATION 



The ENDIF directive marks the end of an IF. ..ENDIF or IF. ..ELSE. 
See the IF directive. 



.ENDIF block of statements. 
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ENDM 

Ends macro definition 









SYNTAX 


Lsbsi 


i"in*»rj*fir»n 
~- r""» 

ENDM 


O n erand 





EXPLANATION 

The ENDM directive marks the end of a macro definition. See the MACRO directive. 
The ENDM directive must not have a label. 
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Ends REPEAT block 
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SYNTAX 


Label 


Operation 


Operand 




[symbol] 


ENDR 







EXPLANATION 



The ENDR directive marks the end of a REPEAT. ..ENDR block of statements. See the REPEAT 
directive. 
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EQU 



Assigns value to symbol 







SYNTAX 




Label 


Operation 


Operand 




[symbol] 


EQU 


numeric-value 





PARAMETERS 



symbol A user-defined symbol to be assigned a value by this statement. 

numeric-value Any numeric expression. Each symboi in the expression must have been 

defined previously. 



EXPLANATION 

The EQU directive assigns a value to a symbol. The symbol cannot be redefined in the same 
source module. 

A symbol defined in an EQU directive may be used by any statement in the module, with the 
following restriction: a BLOCK, EQU, IF, ORG, REPEAT, SET, or STRING directive that refers 
to the symbol must not precede the EQU directive that defines the symbol. 



EXAMPLES 



Label 



Operation Operand 



MVI 
MVI 



B,R0WS 
C,COLS 



Comment 

; NUMBER OF ROWS TO B REGISTER. 
: NUMBER OF COLUMNS TO C REGISTER, 



ROWS 
COLS 



EQU 
EQU 



10 
3 



DEFINE NUMBER OF ROWS... 
... AND NUMBER OF COLUMNS 



TABLE 



BLOCK 



R0WS*C0LS 



ALLOT SPACE FOR A 30-BYTE TABLE. 



The symbol ROWS is assigned the value 10 and the symbol COLS is assigned the value 3. 
Note that the two 8080A MVI instructions may refer to ROWS and COLS, even though the 
symbols are not defined until later in the module. On the other hand, the BLOCK directive 
that refers to the symbols must follow the EQU directives that define the symbols. 



(a) 
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Stops macro expansion 









SYNTAX 


Label 


Operation 


Operand 




[symbol] 


EXITM 







EXPLANATION 

The EXITM directive terminates the current macro expansion; EXITM does not mark the end 
of a macro definition. 

EXITM is valid only in macros. It is generally used to stop macro expansion in the middle of 
an IF block or REPEAT block. 

EXAMPLES 

Label Operation Operand Comment 



MACRO TESTBYTE 

PARAM SET 1 

REPEAT PARAM <= •#' 

IF 'PARAM' < 



POINT TO FIRST PARAMETER. 
DO FOR EVERY PARAMETER: 
IF PARAMETER IS BAD... 
WARNING ; NEGATIVE PARAMETER 

EXITM ; ... ABORT MACRO EXPANSION. 

ELSE ; OTHERWISE STORE THE VALUE. 

BYTE 'PARAM' 
ENDIF 
PARAM SET PARAM + 1 ; INCREMENT PARAMETER POINTER... 

ENDR ; ... AND REPEAT. 

ENDM 

Macro TESTBYTE generates one BYTE directive for each parameter in the macro invocation. 
The variable PARAM counts from 1 to the number of parameters passed ('#'). The construct 
'PARAM' is replaced by the parameter pointed to by PARAM. If a negative parameter is 
encountered, the WARNING and EXITM directives are assembled and macro expansion ends 
before all parameters have been processed. 

The macro invocation 

TESTBYTE 10,20,-1,-2,30 

yields the following macro expansion: 

BYTE 10 
BYTE 20 
WARNING ; NEGATIVE PARAMETER 

If the EXITM statement were omitted, macro expansion would continue until all parameters 
were processed: 

BYTE 10 

BYTE 20 

WARNING ; NEGATIVE PARAMETER 

WARNING ; NEGATIVE PARAMETER 

BYTE 30 
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Declares global symbol(s) 







OV/MT" A \f 


La be! 


Operation 


Operand 


[symboi] 


GLOBAL 


giobal-sym[,giobai-sym]... 



PARAMETERS 



global-sym A symbol to be declared global. 



EXPLANATION 



The GLOBAL directive declares one or more symbols to be global. A global symbol defined in 
one module may be referred to by other modules. Both the module that defines the symbol 
and the module that refers to it must declare the symbol to be global. The linker will make 
the value of the global symbol available to all modules that declare it. 

The GLOBAL directive that declares a symbol must precede the statement that defines that 
symbol. The symbol may not be defined more than once in any group of modules to be linked. 



A global symbol that is given a value in the current module is called a bound global. A bound 
global that is also an address is called an entry point, since it often represents an instruction 
that is jumped to from outside the module. 

A global symbol that is not defined in the current module is called an unbound global; its 
value must be provided at link time, either by another module or by the linker command 
DEFINE. 

A section name (defined by a COMMON, RESERVE, or SECTION directive) is a global symbol; 
it should not be declared with a GLOBAL directive in the same module in which the section 
is defined. 



5-17 



GLOBAL 

Declares global symbol(s) 
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EXAMPLES 

This example demonstrates the use of global symbols in three modules: MYMOD, HISMOD, 
and HERMOD. 



Label 



Operation Operand 

NAME MYMOD 

GLOBAL HIM, HER, VALUE 



VALUE 



EQU 
CALL 
CALL 
CALL 



3 

HIM 
HER 
MYSELF 



MYSELF 



XRA 



In module MYMOD, HIM and HER are unbound globals, but VALUE is a bound global, since it 
is assigned a value by the EQU directive. MYSELF does not need to be declared global, since 
it is defined in MYMOD (as the address of the 8080A XRA instruction) and is not used in any 
other module. 



HIM 



NAME 


HISMOD 


GLOBAL 


HIM, VALUE 


MVI 


A, VALUE 



In module HISMOD, VALUE is an unbound global. HIM is defined as the address of the MVI 
instruction, so HIM is an entry point (a bound global address). 



HER 



NAME 

GLOBAL 

CALL 



HERMOD 
HER, HIM 
HIM 



In module HERMOD, HIM is an unbound global. HER is defined as the address of the CALL 
instruction, so HER is an entry point. 

In summary: 

• HIM is defined in HISMOD and used in MYMOD and HERMOD; 

• HER is defined in HERMOD and used in MYMOD; 

• VALUE is defined in MYMOD and used in HISMOD. 



Each symbol is declared to be global wherever it is defined or used. Since MYSELF is defined 
in MYMOD and used only in MYMOD, it does not need to be declared global. 
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Begins conditional assembly block 







SYNTAX 


■ _ 1 1 

LdUBI 


ufjeicuiuii 


r\_ i 


[symbol] 


IF 


condition-value 



PARAMETERS 

condition-value Any expression that yields a numeric value. The condition is considered 
false if the value is zero and true if the value is nonzero. 

EXPLANATION 

The IF directive marks the beginning of an IF...ENDIF or IF...ELSE...ENDIF block of statements. 
The value of the expression in the IF directive determines which statements (if any) in the 
block are assembled. 



IF...ENDIF 

An IF...ENDIF block has the following structure: 
IF condition-value 

(statements to be assembled if condition-value is true) 
ENDIF 

If the condition-value is true (nonzero), the statements between the IF directive and the 
ENDIF directive are assembled. If the condition-value is false (zero), those statements are 
skipped. (See Example 1.) 

IF.. .ELSE. ..ENDIF 

An IF.. .ELSE. ..ENDIF block has the following structure: 
IF condition-value 

(statements to be assembled if condition-value is true) 
ELSE 

(statements to be assembled if condition-value is false) 
ENDIF 

If the condition-value is true (nonzero), the statements between the IF directive and the ELSE 
directive are assembled. Otherwise, the statements between the ELSE directive and the 
ENDIF directive are assembled. (See Example 2.) 

NOTE 

A relational expression (for example, J < O) yields the value -1 (16 1 -bits) 
when true and the value (16 O-bits) when false. Thus the bit manipulation 
operators &, !, and !! may be used as the conjunctions AND, OR, and 
exclusive-OR, respectively, in complex relational expressions. (See Example 
3.) The Language Elements section of this manual explains expressions and 
operators in detail. 
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Each IF directive must have a corresponding ENDIF directive and may have one 
corresponding ELSE directive. 

An IF block may be nested inside a REPEAT block or another IF block. Blocks may be nested 
as deep as available memory in the assembler permits. An IF block may not lie partially inside 
and partially outside a REPEAT block, another IF block, a macro expansion, or statements 
from an INCLUDE file. See Fig. 5-1, which illustrates the allowed forms of nesting for IF 
blocks. 



Allowed 



REPEAT 



E' F 

I FN 



ENDIF 
ENDR 



IF 



start of macro 
expansion 

end of macro 
expansion 

ENDIF 



E 



IF 



E 



start of 
INCLUDE file 
end of 
INCLUDE file 



ENDIF 



IF 

REPEAT 
ENDR 

ELSE 



E 



E ,F 

I EN 



ENDIF 
ENDIF 



start of macro 
expansion 

IF 



E 



ENDIF 



end of macro 
expansion 



start of 
INCLUDE file 



E 



IF 
ENDIF 



end of 
INCLUDE file 



NOT Allowed 



REPEAT 
IF 

ENDR 
ENDIF 



IF 



start of macro 
expansion 



ENDIF 

end of macro 
expansion 



IF 



start of 
INCLUDE file 



ENDIF 



end of 
INCLUDE file 
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Fig. 5-1. Allowed forms of IF block nesting. 



An IF block may not lie partially inside and partially outside a REPEAT block, another IF block, a macro 
expansion, or statements from an INCLUDE file. 
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IF 



Begins conditional assembly block 



EXAMPLES 

IF Example 1 

In this example, a warning is displayed at assembly time if the object code for section ASEC 
occupies more than one page of memory. The dollar sign represents the current value of the 
iocation counter. 



Label 



PAGES! ZE 



Operation Operand 



EQU 
SECTION 



100H 
ASEC,INPAGE 



IF 

WARNING 

ENDIF 



$ >= PAGESIZE 
SECTION ASEC TOO LONG 



IF Example 2 

This example shows the use of an IF. ..ELSE. ..ENDIF block in a macro. 

Label Operation Operand Comment 
MACRO WORDS 



IF 

WORD 
ELSE 

WORD 
ENDIF 



" * 1 » " = "" ; IF FIRST PARAMETER IS ABSENT... 
; ... STORE A WORD OF ZEROS. 

M' : OTHERWISE STORE FIRST PARAMETER 



ENDM 

The construct "1 ' is replaced by the first parameter. If there is no first parameter, "T is 
replaced with the null string (nothing); since the expression "" = "" is true, the statement 
WORD is assembled and the statement WORD T is skipped. On the other hand, if the 
parameter exists, the second WORD directive is assembled, taking the parameter as its 
operand. 



IF Example 3 

Label Operation 

IF 

WARNING ; 
ENDIF 



Operand 

M>N & N<P & P=Q 

TROUBLE 



In this example, the conditional expression of the IF statement contains three relational 
subexpressions: "M>N", "N<P", and "P=Q". Each subexpression yields the value -1 (true) or 
(false). The three subexpression values are ANDed together to yield the value (-1 or 0) to be 
used by the IF directive. (& is the logical AND operator.) Thus the WARNING directive is 
assembled only if: 

• M is greater than N, and 

• N is less than P, and 

• P is equal to Q. 



(a- 
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Assembles source code from another file 
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SYNTAX 


Label 


Operation 


Operand 


[symbol] 


INCLUDE 


filename-string 



PARAMETERS 



filename-string 



An expression that yields a string with the format filename or 
filename/n, where filename is any TEKDOS file name and n is the disc 
drive number. If no drive is specified, the system disc is assumed. 



EXPLANATION 



The INCLUDE directive causes the assembler to process the statements in the specified file 
as if they were part of the current source file. 

The INCLUDE file may not contain an INCLUDE directive. 

If the INCLUDE directive is contained in a macro, the file is included at macro expansion time. 
However, statements in the INCLUDE file cannot use the special text substitution constructs 
usually allowed in macros ('N' for the Nth parameter, '#' for the number of parameters, '@' 
for a unique label). See the Macros section for information about these constructs. 



EXAMPLES 



Label 



Operation Operand 



NAME 

INCLUDE 

INCLUDE 



MAINMOD 
"MACROS" 
" COMMON /1" 



Comment 



DEFINE STANDARD MACROS, 
DEFINE COMMON BLOCK. 



In this example, the statements in file MACROS on the system disc and file COMMON on 
disc 1 are assembled at the beginning of module MAINMOD. MACROS contains macro 
definition blocks; COMMON defines a common section. 



522 
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LIST 



i urns on listing options 







SYNTAX 


Label 


Operation 


Operand 


[symbol] 


LIST 


[listing-option[, listing-option]...] 



PARAMETERS 

listing-option One of the following listing options: 

CND— Lists statements that are not assembled because of unsatisfied 
!F or REPEAT conditions. Defaults to OFF: only those statements that are 
actually assembled are listed. 

CON— Lists assembly errors on the system terminal as well as in the 
source listing. Defaults to ON. 

DBG— Causes the linker listing to include an internal symbols list for 
this module at link time. Defaults to OFF. 

ME— -Sets the ME/MEG option to the ME setting: lists all macro 
expansion statements that are assembled. The ME/MEG option defaults 
to MEG. 

MEG— Sets the ME/MEG option to its default setting, MEG: lists only 
those macro expansion statements that generate object code. 

SYM— Lists the symbol table. Defaults to ON. 

TRM — Trims the assembler listing to 72 characters. The listing width 
defaults to 72 characters wide if the listing device is CONO; otherwise 
the width defaults to 132 characters. 

If no option is specified, the source listing is turned ON. 

EXPLANATION 

The LIST directive turns on the listing option(s) named in the operand field. If no option is 
named, the master option (which controls the source listing) is turned on. The NOLIST 
directive may be used to turn any of these options off. 

Each option controls a different listing feature and may be turned on or off anywhere in the 
source module. If an option is changed during a macro expansion, its previous setting is 
restored when the expansion ends. 
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Turns on listing options 



An assembler listing contains two parts: the source listing, which shows the source code 
and object code for each statement assembled; and the symbol table, which lists the 
symbols used in the source module. The master option, CND option, and ME/MEG option 
determine which lines of code appear in the source listing, and are discussed in the following 
paragraphs. The SYM option controls display of the symbol table, and is discussed with the 
CON, DBG, and TRM options under the heading Other Options. 



Source Listing 

Master Option. The master option is normally ON. The directive NOLIST (without operands) 
turns the master option OFF, suppressing display of all statements except erroneous ones. 
When the master option is OFF, PAGE and SPACE directives are suppressed and the CND 
and ME/MEG options are overridden. The directive LIST (without operands) turns the master 
option back ON. 

CND. Normally the CND option is OFF, and any statement that is not assembled because of 
an unsatisfied IF or REPEAT condition is not listed. When the CND option is ON, even 
unassembled statements are listed. 



ME/MEG. The ME/MEG option controls the display of statements in macro expansions. It 
has three settings: ME, MEG, and OFF. At the default setting, MEG, only those statements 
that generate object code (assembly language instructions and ASCII, BLOCK, BYTE, and 
WORD directives) are listed. Note that other directives that directly affect the object module 
(COMMON, EQU, GLOBAL, NAME, ORG, RESERVE, RESUME, SECTION) are not listed. 

The directive LIST ME changes the ME/MEG setting to ME, causing every assembled 
statement in a macro expansion to be listed. The directive NOLIST ME or NOLIST MEG turns 
the ME/MEG option OFF, suppressing display of all macro expansion statements except 
erroneous ones. The directive LIST MEG returns the ME/MEG option to its default setting. 

Summary. The following table shows how the master option and CND option control the 
display of statements outside macro expansions. 



Option 


Settings 




Master 


CND 


Type of Statements Listed 


OFF 

ON 

ON 


a 

OFF 
ON 


errors 

assembled statements (default) 

all statements 



a don't care 
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LIST 



is on listing options 



The following table shows how the master option, ME/MEG option, and CND option control 
the display of statements in a macro expansion. 



Opt 


ion Settings 






Master 


ME/MEG 


CND 


Type of Statements Listed 


OFF 

ON 

ON 

ON 

ON 


a 

OFF 
MEG 
ME 
ME 


a 
a 
a 

OFF 
ON 


errors 

errors 

statements that generate object 

assembled statements 

all statements 


code (default) 



3 don't care 



Other Options 

CON. Normally the CON option is ON, and every erroneous statement and its accompanying 
error message are displayed on the system terminal (CONO) as well as in the source listing. 
When the CON option is OFF, erroneous statements and their error messages appear only in 
the source listing. 



DBG. If the DBG option is left at its default setting (OFF), the linker listing will contain no 
internal symbols list for the current module when the module is linked. If the DBG option is 
ON when assembly ends, an internal symbols list will be created, and it will list all symbols 
in the module. The internal symbols list is described in the Linker section of this manual. 



SYM. If the SYM option is left at its default setting (ON), the assembler listing will contain 
the symbol table as well as the source listing. If the SYM option is OFF when assembly ends, 
no symbol table is listed. The symbol table is described in the Assembler Introduction section. 



TRM. Normally, the TRM option is OFF, and the assembler listing contains lines of up to 1 32 
characters. When the TRM option is ON, all lines are truncated to 72 characters. (Source 
lines that contain more than about 50 characters are truncated, since the source listing 
displays 20 to 25 characters of information— depending on your microprocessor— to the left 
of each source line.) If TRM is ON when assembly ends, the symbol table is rearranged to fit 
a 72-character format. 

When the listing device is the system terminal (CONO), the TRM option is automatically 
turned ON before assembly starts. The directive NOLIST TRM restores the 132-character 
format. 



O 
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Turns on listing options 



EXAMPLES 

Label Operation Operand 

LIST DBG 

This statement causes the linker to display an internal symbols list for this module when it is 
linked. 

LIST CND,ME 

This directive causes all statements (assembled and unassembled, mainline statements and 
macro expansion statements) to appear in the source listing. 

NOLIST 

LIST 

The NOLIST directive turns off the source listing and the LIST directive turns it back on. 
While the source listing is suppressed, the settings of other options may be changed; 
however, changes to the CND and ME/MEG options do not become apparent until the listing 
is turned back on. 

NOLIST SYM 

This statement suppresses display of the symbol table. 
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MACRO 

Begins macro definition 









SYNTAX 


La be! 


Operation 


Operand 




[symbol] 


MACRO 


macro-name 





macro-name 



PARAMETERS 

The name of the macro being defined. 



EXPLANATION 

The MACRO directive marks the beginning of a macro definition block. The macro consists of 
all statements between, but not including, the MACRO directive and the next ENDM 
directive. 

The Macros section of this manual describes macros in detail. 



EXAMPLES 

The following macro converts the number in the specified 8080A register to its two's 
complement: 



Label 



Operation Operand Comment 



MACRO 


NEGATE 


SUB 


A 


SUB 


'1 ' 


MOV 


M » ,A 


ENDM 





SET A TO ZERO. 
SUBTRACT '1 ' FROM ZERO. 
STORE RESULT BACK INTO '1'. 



The macro invocation 
NEGATE 



B 



yields the following macro expansion: 



SUB 
SUB 
MOV 



A ; SET A TO ZERO. 

B ; SUBTRACT B FROM ZERO. 

B,A ; STORE RESULT BACK INTO B. 



Every occurrence of the first formal parameter ('1') is replaced by the first actual parameter 
(B). The 8080A instruction SUB A clears the A register; SUB B subtracts the contents of the 
B register from the A register; MOV B,A moves the result back into the B register. 



(S 
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NAME 



Declares object module name 
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SYNTAX 


Label 


Operation 


Operand 


[symbol] 


NAME 


module-name 



PARAMETERS 



module-name A name for the object module being created: any symbol. 



EXPLANATION 



The NAME directive gives a name to the object module created by this assembly. If more than 
one NAME directive appears in a module, only the first name specified is used. If the source 
module contains no NAME directive, the default name *NONAME* is assigned to the object 
module. 

The library generator (LibGen) requires that each module in a library file have a unique 
name. 



EXAMPLES 

Label Operation Operand 

NAME SUBSMOD 

This statement assigns the name SUBSMOD to the object module being created. 
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NOLIST 

Turns off listing options 







SYNTAX 


i flhf^i 


O Deration 


Operand 


[symbol] 


NOLIST 


[listing-option[, listing-option]...] 



PARAMETERS 

listing-option One of the following listing options: 

CND — Suppresses listing of statements that are not assembled because 
of unsatisfied IF or REPEAT conditions. 

CON — Suppresses display of assembly errors on the system terminal. 

DBG — Suppresses the internal symbols list for this module at link time. 

ME — Suppresses display of all macro expansion statements. 

MEG — Suppresses display of all macro expansion statements. 

SYM — Suppresses listing of the symbol table. 

TRM — Changes the listing width from 72 characters to 132 characters. 

If no option is specified, the source listing is turned off. 

EXPLANATION 



The NOLIST directive turns off the listing option(s) named in the operand field. These options 
are explained in detail under the LIST directive. 



(a) 
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Sets location counter 
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SYNTAX 


Label 


Operation 


Operand 
(address ) 


[symbol] 


ORG 


(/address-mod) 



PARAMETERS 

symbol A user-defined label (usually omitted) that is assigned the value of the 

updated location counter. 

address A new value for the location counter: any expression that yields an 

address. Each symbol in the expression must have been defined 
previously. 

address-mod Any numeric expression. The location counter is advanced to the next 

address that is a multiple of the address-mod. Each symbol in the 
expression must have been defined previously. 

EXPLANATION 

The ORG directive sets the location counter to the specified address. 

If the / (slash) operator is used, the location counter is set to the next address that is a 
multiple of the address-mod. If the current value of the location counter is already a multiple 
of the address-mod, the location counter is unaffected. If the address-mod is zero and the 
value in the location counter is even, the location counter is set to the next odd value. 

The location counter is an internal counter maintained by the assembler that holds the 
address, relative to the beginning of the current section, of the next byte of code to be 
assembled. The location counter starts at zero for each section and is automatically updated 
as object code is generated. 

The ORG directive is generally used to initialize the program counter for an absolute section, 
or to begin the next block of object code on a new page of memory. Avoid using ORG in a 
byte-relocatable or inpage-relocatable section, since the conditions you use ORG to create 
are likely to be lost when the section is relocated. 

If, through use of the ORG directive, you break your section into noncontiguous blocks of 
code, the linker may place other sections in the gaps between these blocks. (See Example 1 .) 
Every byte in a section retains its position relative to the beginning of the section even if the 
section is relocated. 

If you use ORG incorrectly, you may end up specifying more than one value for the same byte 
of object code. (See Example 2.) Such a situation is not detected by the assembler, linker, or 
LOAD command. 



D-JU 
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ORG 

Sets location counter 



EXAMPLES 



ORG Example 1 

Label Operation Operand Comment 



; DEFINE 


SECTION 


ABS 


(AN ABSOLUTE SECTION) . 




SECTION 


ABS, ABSOLUTE 




ORG 




100H 


START ON PAGE 1. 


ABS1 


m nrv 




80 H 


. 10Q nvTcc nc Mrunov 










ORG 




/100H 


GO TO BEGINNING OF NEXT PAGE. 


ABS2 


BLOCK 




40 H 


; 64 BYTES 




ORG 




400H 


GO TO PAGE 4. 


ABS3 


BLOCK 




80 H 


; 128 BYTES 


; DEFINE 


SECTION 


REL 


(A BYTE-RELOCATABLE SECTION). 




SECTION 


REL 




REL1 


BLOCK 




40H 


64 BYTES 




ORG 




/100H 


; GO TO BEGINNING OF NEXT PAGE (?) 


REL2 


BLOCK 




80H 


128 BYTES 



In the example above, two sections of object code are generated. Section ABS is divided into 
three blocks and section REL is divided into two blocks. The layout of the two sections is 
shown below. 



0000 



ABS 



0100 



0200 



0300 



0400 



ABS1 



ABS2 



ABS3 



0000 



REL 



0100 




3454-14 
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ORG 

Sets location counter 
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The linker will arrange the two sections as shown below. 



uuuu 
0100 




ABS1 


0200 




ABS2 




REM 


0300 






REL2 






0400 


ABS3 



>V 



Section REL is relocated as a whole 
to the first gap of sufficient size. 



J 



3454-15 



Notice that section REL is placed between blocks ABS2 and ABS3 of section ABS. Notice also 
that block REL2 began on a page boundary before it was relocated, but not after. 



ORG Example 2 

Label Operation Operand 



ORG 
ASCII 
ORG 
ASCII 


400H 

"A LINE OF TEXT" 

405H 


e object 


code as: 


ORG 
ASCII 


400H 

"A LIN*«*»*TEXT M 
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PAGE 

Skips to new page in listing 









SYNTAX 


l_oKoj 


Hnaratinn 


Hnoran/i 




[symbol] 


PAGE 







EXPLANATION 



A PAGE directive causes the next source line listed to appear at the top of a new page. The 
PAGE directive itself is not listed. 

If the source listing is suppressed by a NOLIST directive, the PAGE directive has no effect. 



EXAMPLES 

Label Operation Operand Comment 

TITLE "THIS IS THE TITLE" 



PAGE ; SKIP TO A NEW PAGE TO 

SECTION MAIN ; BEGIN CODE FOR MAIN. 



These statements cause the source code for section MAIN to begin on a new page. The top of 
the new page looks like this: 

Tektronix xxxxxxxxx ASM Vx.x THIS IS THE TITLE Page x 



xxxxx 



SECTION 



MAIN 



; BEGIN CODE FOR MAIN. 
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Begins repetitive assembly 







SYNTAX 


Label 


Operation 


Operand 


[symbol] 


REPEAT 


condition- value[, limit] 



PARAMETERS 



condition-value Any expression that yields a numeric value. The condition is considered 
false if the value is zero and true if the value is nonzero. 

limit The maximum number of times the block may repeat: any non-negative 

scalar expression. Defaults to 255. 



EXPLANATION 



The statements between a REPEAT directive and its matching ENDR directive are assembled 
repeatedly until the condition-value becomes false (zero). A REPEAT.. .ENDR block is valid 
only within a macro. 

If the condition-value is still true (nonzero) after the repetition limit has been reached, the 
assembler responds 

••«•* ERROR 017: Iteration Halt exceeded 

and skips to the statement following the ENDR directive. 

If the condition-value is false before the first repetition, the REPEAT... ENDR block is not 
assembled at all. 

The condition-value may be a relational expression (for example, J < 0). See the IF directive 
for a note on the relationship between numeric and relational expressions. 

A REPEAT block may be nested inside an IF block or another REPEAT block. Blocks may be 
nested as deep as available memory in the assembler permits. A REPEAT block may not lie 
partially inside and partially outside an IF block, another REPEAT block, a macro expansion, 
or statements from an INCLUDE file. See Fig. 5-2, which illustrates the allowed forms of 
nesting for REPEAT blocks. 
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REPEAT 

Begins repetitive assembly 



Allowed 


NOT Allowed 








1 IF 

I ENDIF 


1 REPEAT 

1 ENDR 






1 IF 

-ENDR 




1 REPEAT 

I ENDR 


ENDIF 




-ENDIF 








start of macro 


start of macro 
expansion 










expansion 








KtrtAI 




i REPEAT 

1 ENDR 




REPEAT 






start of macro 
expansion 






r— another 

macro 
1 expansion 






- ENDR 








end of macro 






end of macro 




expansion 


expansion 






1 ENDR 








end of macro 
expansion 












start of 
INCLUDE file 










-REPEAT 








KfcPfcAT 




start of 
I INCLUDE file 

I end of 

INCLUDE file 


| REPEAT 

1 ENDR 






start of 
INCLUDE file 

-ENDR 












end of 
INCLUDE file 




end of 




LlMUH — 


INCLUDE file 


3454-16 



Fig. 5-2. Allowed forms of REPEAT block nesting. 



A REPEAT block may not lie partially inside and partially outside an IF block, another REPEAT block, a 
macro expansion, or statements from an INCLUDE file. 



(a) 
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Begins repetitive assembly 
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EXAMPLES 



Label 


Operation 


Operand 


COUNT 
COUNT 


MACRO 

SET 

REPEAT 

BYTE 

SET 

ENDR 

ENDM 


LOOP 

1 

COUNT <= M« 

COUNT + 1 


The statement 







LOOP 3,0 

invokes the above macro and produces the following expansion: 



COUNT 


SET 


1 






REPEAT 


COUNT 


<= 3 




BYTE 







COUNT 


SET 
ENDR 


COUNT 


+ 1 




REPEAT 


COUNT 


<= 3 




BYTE 







COUNT 


SET 
ENDR 


COUNT 


+ 1 




REPEAT 


COUNT 


<= 3 




BYTE 







COUNT 


SET 
ENDR 


COUNT 


+ 1 



(COUNT is incremented to 2.) 



(COUNT is incremented to 3.) 



(COUNT is incremented to 4.) 



This sequence generates three bytes of zeros. Note that with the listing options at their 
default settings, only the BYTE directives would appear in the listing: 



BYTE 
BYTE 
BYTE 



See the LIST directive for more information on listing options. 
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RESERVE 

Reserves section of memory 







SYNTAX 


Label 


Operation 


Operand 


[symbol] 


RESERVE 


section-name,section-length[, relocation-type] 



PARAMETERS 



symbol 

section-name 

section-length 

relocation-type 



A user-defined label (usually omitted) that represents the first byte of 
the relocated reserve section. 

The name assigned to the section. 

The number of bytes in the section: any non-negative scalar expression. 

An option to direct the relocation of the section at link time. You may 
specify one of the following relocation types: 

PAGE — The section is relocated to the beginning of a page of memory. 
See the Assembler Specifics section of this manual for the page size for 
your microprocessor. 

INPAGE — The section may be relocated to any address, so long as the 
entire section lies within one page of memory. 

If you do not specify PAGE or INPAGE, the relocation type defaults to 
byte-relocatable: the relocated section may begin at any byte in 
memory. 

EXPLANATION 

The RESERVE directive creates a section with the specified name, length, and relocation 
type. Different modules may allocate space for the same reserve section; the linker 
concatenates all reserve sections with the same name into a single section. 

Since you can specify the length, but not the contents, of a reserve section, RESERVE is used 
chiefly to set aside memory for a workspace or stack. 

A reserve section may not have the relocation type ABSOLUTE; however, you may use the 
linker command LOCATE to place the section at the desired position in memory. See the 
Linker section of this manual. 

The RESERVE directive has no effect on the section currently being defined. 

The relocation type of. a reserve section must be the same everywhere the section is 
declared. A section must not be declared more than once in the same module. 

The name of a section is a global symbol whose value is the address of the first byte of the 
section. A section name should not be declared with a GLOBAL directive in any module in 
which the section is defined with a RESERVE directive. 



<a 
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RESERVE 

Reserves section of memory 
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EXAMPLES 



Label 



Operation Operand 



NAME 
SECTION 



M0D1 
SEC1 



Comment 



; BEGIN DEFINITION OF SEC1. 



RESERVE STACK, 40 



; SET ASIDE 40 BYTES FOR STACK, 
; RESUME DEFINITION OF SEC1. 



In the above example, 40 bytes are allocated to a byte-relocatable reserve section called 
STACK. The statements on either side of the RESERVE directive refer to section SEC1. 



NAME 



MOD2 



RESERVE STACK, 20 ; SET ASIDE 20 BYTES FOR STACK. 

When modules MOD1 and MOD2 are linked, reserve section STACK will occupy 60 bytes of 
memory: 40 bytes from MOD1 and 20 bytes from MOD2. 
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RESUME 

Resumes definition of section 







SYNTAX 


Label 


Operation 


Operand 


[symbol] 


RESUME 


[section-name] 



PARAMETERS 



symbol 



A user-defined label (usually omitted) that is assigned the current value 
of the location counter of the resumed section. 



section-name The name of the section to be resumed. If no name is given, the default 

section is resumed. 



EXPLANATION 



The RESUME directive stops definition of the current section and resumes the definition of 
the specified section. 

If no section name is given, the definition of the default section is continued. The default 
section is described under the SECTION directive. 

Once a section is defined, it may be resumed any number of times. 



EXAMPLES 

Label Operation Operand Comment 

SECTION MAINPROG ; BEGIN DEFINITION OF MAINPROG, 



TEMP 



STA TEMP 

SECTION RAM 

BLOCK 1 

RESUME MAINPROG 



USE A TEMPORARY LOCATION. 
SWITCH TO RAM ... 
...TO ALLOT SPACE FOR TEMP, 
GO BACK TO ORIGINAL SECTION, 



In this example, the definition of section MAINPROG is interrupted to reserve one byte for 
temporary storage. The RESUME directive continues the definition of section MAINPROG. 



@ 
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SECTION 

Declares program section 
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SYNTAX 


Label 


Operation 


Operand 


[symbol] 


SECTION 


section-namef, relocation-type] 



PARAMETERS 



symbol 



A user-defined label (usually omitted) that represents the address of the 
first bvte of the section. 



section-name The name assigned to the section. 

relocation-type An option to direct the relocation of the section at link time. You may 

specify one of the following relocation types: 

PAGE — The section is relocated to the beginning of a page of memory. 
See the Assembler Specifics section of this manual for the page size for 
your microprocessor. 

INPAGE — The section may be relocated to any address, so long as the 
entire section lies within one page of memory. 

ABSOLUTE — The section is not relocated. 

If you do not specify PAGE, INPAGE, or ABSOLUTE, the relocation type 
defaults to byte-relocatable: the relocated section may begin at any byte 
in memory. 



EXPLANATION 



The SECTION directive declares a section of type SECTION and defines the name and 
reiocation type of the section. The contents of the section are defined by the statements 
following the SECTION directive, up to the next SECTION, COMMON, or RESUME directive. 

Any section that contains instructions (as opposed to data) should be of type SECTION. 

NOTE 

In this discussion, the word "SECTION" (all uppercase) refers to a section 
declared with a SECTION directive, rather than with a COMMON or RESERVE 
directive. 



540 



Assembler Directives— 8002A: Assembler Users Manuai SECTION 

Declares program section 
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the RESUME directive to add code to a section that has already been defined in the current 
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issues an error message and links only the first SECTION with that name. 

The name of a section is a global symbol whose value is the address of the first byte of the 
section. A section name should not be declared with a GLOBAL directive in the same module 
in which the section is defined with a SECTION directive. 

The default section of a module contains all object code generated before the first SECTION 
or COMMON directive is assembled. The default section is a byte-relocatable SECTION; its 
name is derived as follows; 

1. Take the first seven characters of the name of the object file. 

2. Eliminate all characters except letters and digits. 

3. Add the prefix "%". 

For example, the default section for object file MYPROG;0 is %MYPROG. When no object file 
is generated, the default section is called %. 



EXAMPLES 



Label Operation Operand 

SECTION MAINPROG 

(source code for section MAINPROG) 



SECTION TABLE, INPAGE 

(source code for section TABLE) 



SECTION INTERRUP, ABSOLUTE 

ORG 100H 

(source code for section INTERRUP) 



In this example, section MAINPROG may be relocated by the linker to any address. TABLE is 
relocatable to any address, so long as the entire section lies within one page of memory. 
INTERRUP, which is not relocatable, begins at address 100H. 
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SET 

Assigns value to variable 
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SYNTAX 


Label 


Operation 


Operand 


string-variable 


SET 


string-expression 


or 






numeric-variable 


SET 


numeric-expression 



PARAMETERS 

string-variable A user-defined label for a string variable, 

numeric-variable A user-defined label for a numeric variable, 

string-expression Any expression that yields a character string, 

numeric-expression Any expression that yields a numeric value. 

EXPLANATION 

The SET directive assigns a value to a symbol. The symbol is called a variable because it may 
be assigned a new value with a subsequent SET directive. A variable may be used anywhere 
the value it represents is permitted. 

A variable must not be a global symbol. SET may not redefine a symbol unless that symbol 
was originally defined with a SET directive. 

There are two types of variables: string and numeric. 

• A string variable represents a character string. A string variable must be declared with 
a STRING directive before it may be assigned a value. 

• A numeric variable represents a scalar or address. A numeric variable need not be 
declared; it becomes defined the first time a SET directive assigns it a value. 

If the type of the variable does not match the type of the value assigned to it, the value is 
converted to match the type of the variable. 

• If you assign a string value to a numeric variable, the variable takes the 16-bit value 
formed by the first two bytes of the string. If the string exceeds two characters, the 
assembler responds 

»**«* ERROR 085: String value too large 

If the string contains only one character, its ASCII code is copied to the low-order byte 
of the variable and the high-order byte is set to zero. 

• If you assign a numeric value to a string variable, the STRING function is automatically 
invoked to convert the number to a six-digit string. 
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SET 



Assigns value to variable 



Text substitution (signaled by single quotes ' ') often involves variables. A string variable in 
single quotes (e.g., 'STVAR') is replaced by the string the variable represents. The substituted 
string is not enclosed in quotes. A numeric variable in quotes (e.g., 'N') is iegai oniy in 
macros, and is replaced by the Nth parameter in the macro invocation. 



Label 

N 

N 



Operation Operand 



EXAMPLES 



Comment 



MACRO 

SET 

REPEAT 

BYTE 

SET 

ENDR 

ENDM 



BYTES 

1 

N <= •#• 

»N' ,- f N' 

N+1 



SET POINTER TO FIRST PARAMETER. 
REPEAT FOR EACH PARAMETER: 
ALLOCATE TWO BYTES FOR THE NTH PARAM, 
INCREMENT PARAMETER POINTER. 



In this example, N is a numeric variable that counts from 1 to the number of parameters in 
the macro invocation ('#'). The construct 'N' is replaced by the Nth parameter. The invocation 



ALLOCATE TWO BYTES FOR THE NTH PARAM. 
ALLOCATE TWO BYTES FOR THE NTH PARAM. 
; ALLOCATE TWO BYTES FOR THE NTH PARAM. 



In the example below, string variables FILE and DISC are assigned values and then 
concatenated to form the name of an INCLUDE file. 

Label Operation Operand 

STRING FILE(8),DISC(2) 







BYTES 


10, 


20, MAX 


yields 


the 


macro expansion 










BYTE 
BYTE 
BYTE 


10, 
20, 
MAX 


-10 
-20 
,-MAX 



FILE 



SET 



"INCFILE" 



DISC 



SET 



" / 1 " 



INCLUDE FILErDISC 

The statements from file INCFILE on disc 1 are assembled following the INCLUDE directive. 



<a> 
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Assigns value to variable 



In the following example, the name of the current section ('%') is stored in string variable 
SECNAME and is later substituted into the RESUME directive. 



Label Operation Operand 

STRING SECNAME (8) 

SECTION MAINPROG 



SECNAME SET "'%•" 

RESUME 'SECNAME 1 

The above lines are assembled as follows: 

STRING SECNAME(8) 

SECTION MAINPROG 

SECNAME SET "MAINPROG" 

RESUME MAINPROG 
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SPACE 

Inserts blank lines into listing 









SYNTAX 


Label 


Operation 


Operand 




[symbol] 


SPACE 


[line- count] 





line-count 



PARAMETERS 

The number of blank lines to be generated: any expression that yields a 
scalar in the range to 255. Defaults to 1. 



EXPLANATION 

The SPACE directive generates the specified number of blank lines in the source listing. If no 
line count is given, one line is generated. The SPACE directive itself is not listed. 

If the line count exceeds the number of lines left on the current page, the SPACE directive 
merely skips to the top of the next page. 

If the source listing is suppressed by a NOLIST directive, the SPACE directive has no effect. 



EXAMPLES 



Label 



Operation Operand 



; END OF SECTION AAAA. 
SPACE 5 

SECTION BBBB 

; BEGIN SECTION BBBB. 



These lines of code will be listed as follows: 

; END OF SECTION AAAA. 



5 blank lines 



SECTION BBBB 
; BEGIN SECTION BBBB. 



@ 
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STITLE 

Creates listing subtitle 
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SYNTAX 


Label 


Operation 


Operand 


[symbol] 


STITLE 


subtitle-string 



PARAMETERS 



subtitle-string The subtitle for the source listing: any expression that yields a string of 

up to 72 characters. 



EXPLANATION 



The STITLE directive creates a subtitle of up to 72 characters. The subtitle is printed below 
the title line at the top of each page of the source listing. The STITLE directive itself is not 
listed. 

Each subsequent STITLE directive redefines the subtitle. If the STITLE directive precedes the 
first source line listed on the current page, the new subtitle appears on the current page; 
otherwise it first appears on the next page. Thus, if a STITLE directive immediately precedes 
or follows a PAGE directive, the designated subtitle appears at the top of the new page. 

If the subtitle string exceeds 72 characters, only the first 72 are used. 



The STITLE directive is used for program documentation only. You may choose to change the 
subtitle to reflect each new section of code. 
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Creates listing subtitle 



EXAMPLES 



f~\r\a v o 4- i nr\ fir»fli>anH fnmmant' 



TITLE "THIS IS THE TITLE" 
STITLE "SUBTITLE FOR PAGES 1 AND 2" 
; THIS IS THE FIRST LISTABLE LINE. 



r«u£ -, emir iu rHUE. £ . 



PAGE ; SKIP TO PAGE 3. 

STITLE "SUBTITLE FOR PAGE 3" 



The above statements produce the following page headings in the source listing: 

Tektronix xxxxxxxxx ASM Vx.x THIS IS THE TITLE Page 

SUBTITLE FOR PAGES 1 AND 2 

00003 ; THIS IS THE FIRST LISTABLE LINE. 



Tektronix xxxxxxxxx ASM Vx.x THIS IS THE TITLE Page 

SUBTITLE FOR PAGES 1 AND 2 



Tektronix xxxxxxxxx ASM Vx.x THIS IS THE TITLE Page 

SUBTITLE FOR PAGE 3 
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STRING 

Declares string variable(s) 
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SYNTAX 


Label 


Operation 


Operand 


[symbol] 


STRING 


string-variable[(length)][,string-variable[(length)]]... 



PARAMETERS 

string-variable A symbol to be used as a string variable. 

length The length of the longest string that may be assigned to string-variable: 

any expression that yields a positive scalar value. Defaults to 8. 

EXPLANATION 

The STRING directive declares each symbol in the operand field to be a string variable. Each 
symbol may be followed by a non-negative value indicating the length of the longest string 
that may be assigned to that variable. If a maximum length is not specified, it defaults to 
eight characters. 

A symbol must be declared with a STRING directive before it can be used as a string variable. 
When a string variable is declared, its value is the null string (zero characters). Use the SET 
directive to assign a value to a variable. 

EXAMPLES 

Label Operation Operand 

STRING CITY (10), STATE, HOMETOWN (20) 



CITY 



SET 



"BEAVERTON" 



STATE 



SET 



"OREGON" 



HOMETOWN SET 



CITY:", ": STATE 



In this example, the STRING directive declares CITY, STATE, and HOMETOWN as string 
variables with maximum lengths of 10, 8, and 20, respectively. Subsequently, CITY is 
assigned a 9-character string ("BEAVERTON"), STATE is assigned a 6-character string 
("OREGON"),, and HOMETOWN is assigned a 17-character string ("BEAVERTON.. OREGON") 
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TITLE 

Creates listing title 









SYNTAX 


Label 


Operation 


Operand 




[symbol] 


TITLE 


title-string 





title-string 



PARAMETERS 

The title for the source listing: any expression that yields a string of up 
to 30 characters. 



EXPLANATION 

The TITLE directive creates a title of up to 30 characters to be printed at the top of each page 
of the source listing. The TITLE directive itself is not listed. 

Each subsequent TITLE directive redefines the title. If the TITLE directive precedes the first 
source line listed on the current page, the new title appears on the current page; otherwise it 
first appears on the next page. Thus, if the TITLE directive immediately precedes or follows a 
PAGE directive, the new title appears at the top of the new page. 

If the title string exceeds 30 characters, only the first 30 are used. 

The TITLE directive is used for program documentation only. You may choose to use the 
same title throughout the module, or you may change the title or subtitle as often as you 
want. 

EXAMPLES 



Label 



Operation Operand Comment 

TITLE "THE SAME OLD TITLE" 

STITLE "THE SAME OLD SUBTITLE" 



PAGE 



; SKIP TO PAGE 2. 



PAGE ; SKIP TO PAGE 3. 

TITLE "A NEW TITLE" 

The above statements produce the following page headings in the source listing: 



Tektronix xxxxxxxxx ASM Vx.x THE SAME OLD TITLE 
THE SAME OLD SUBTITLE 



Page 



Tektronix xxxxxxxxx ASM Vx.x 

THE SAME OLD SUBTITLE 



THE SAME OLD TITLE 



Page 



Tektronix xxxxxxxxx ASM Vx.x 
THE SAME OLD SUBTITLE 



A NEW TITLE 



Page 



O 



5-49 



WARNING 

Displays warning 
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SYNTAX 


Label 


Operation 


Operand 




[symbol] 


WARNING 


[;message] 





message 



PARAMETERS 

Any user-defined error message. 

EXPLANATION 



When a WARNING directive is assembled, it is treated as an erroneous statement: the 
WARNING line and the message 

»*«»« ERROR 001: 
are displayed on the system terminal and in the source listing. 

You may use the WARNING directive to detect unexpected conditions in your program. 



Label 
PAGESIZE 



EXAMPLES 



Operation Operand 



SET 100H 

SECTION SEC1.INPAGE 



IF $ >= PAGESIZE 

WARNING ; SECTION '%• TOO LONG 
ENDIF 

In this example, section SEC1 must not exceed one page in length. If the location counter ($) 
has exceeded its maximum when the IF directive is assembled, the WARNING is assembled 
and the following message is displayed: 

xxxxx WARNING ; SECTION SEC1 TOO LONG 

***** ERROR 001: 

The construct '%' is replaced by the name of the current section. 
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WORD 

Generates word(s) of data 







SYNTAX 


Labei 


Operation 


Operand 


[symbol] 


WORD 


word-value[, word-value]... 



PARAMETERS 



symbol 



A user-defined label that represents the address of the first byte of data. 



word-value 



Any expression that yields a number in the range -32768 to 65535. 



EXPLANATION 



The WORD directive stores the specified values in consecutive words of the object program. 
Each word consists of two bytes. The low-order byte of the word may precede or follow the 
high-order byte, depending on the convention for your microprocessor. 

Each value may be a scalar in the range -32768 to +32767 or an address in the range to 
65535. Any value outside the range -32768 to 65535 is truncated to 16 bits without notice. 



EXAMPLES 



Label Operation Operand 

YEARS WORD 1775,1812,1861 

POINTER WORD TABLE 



TABLE 



BLOCK 



12 



In this example, the first statement stores three two-byte numbers: 1775, 1812, and 1861. 
YEARS is the address of the first byte of 1775. 

The second statement stores the address of a 12-byte table. POINTER is the address of the 
address stored. A microprocessor with indirect addressing can refer to the table by its 
address (TABLE) or by its indirect address (POINTER). 
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Section 6 
MACROS 



INTRODUCTION 

A macro is a frequently used sequence of assembler statements. Once a group of statements 
is defined as a macro in the beginning of your assembly language program, the macro can be 
invoked many times. 

A macro is invoked with a single line, which generates zero or more lines of assembler 
statements. This invocation is called the macro expansion process. The macro can make use 
of parameters given in the macro invocation line; with conditional assembly, the macro may 
expand differently with each invocation. 

This section describes macro definition, invocation, and expansion. An overview of the entire 
process is given, followed by a detailed description of each phase of the process. The last part 
of this section gives examples of macro usage. 
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MACRO EXPANSION PROCESS 

The macro expansion process is illustrated in Fig. 6-1 



MACRO 

WW 

wwww 
xxxx 

yyyy 

zzzz 
ENDM 



macname -* 



Macro Body 



Macro Definition 



macname parml , parm2, parm3 

vwv -^ 

wwww 
xxxx 

yyyy 

zzzz ^ 



Macro Invocation 



Macro Expansion 



3454-17 



Fig. 6-1 . Sample macro usage. 



The three phases of macro usage are definition, invocation, and expansion. 

Definition. A macro is defined with the MACRO directive. The macro is given a name ("macname" in 
the figure) that is used later to invoke the macro. The sequence of assembler statements that make up 
the macro follows the MACRO directive ("ww", "wwww", "xxxx", "yyw" and "zzzz" in the figure). This 
sequence of statements is sometimes called the body of the macro. An ENDM directive terminates the 
definition. 

The assembler saves the macro name and its associated body for later invocation. The contents of the 
body are ignored until expansion time. 



Invocation. The macro is invoked when the macro name appears in the operation field of an assembly 
language statement. One or more parameters may follow the macro name ("parml", "parm2", and 
"parm3" in the example). These parameters may be used by the body of the macro to control the 
expansion process. 

Expansion. Each line from the macro body is inserted into your assembler source program, as if the 
program were cut apart at the macro invocation and the invocation line replaced with the entire macro 
body. The assembler then interprets the statements within the body as if they were part of the original 
source program. Any line of the body may reference the parameters passed to the macro at invocation 
time; these references can be used to alter the contents of each assembler line. 
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MACRO DEFINITION 

You define a macro once in your program — before its first use. The macro definition consists 
of three parts: 

• the MACRO assembler directive, which gives the name of the macro, 

• the sequence of statements constituting the body of the macro, 

• the ENDM assembler directive, which terminates the macro definition. 

You must define any macro prior to its first invocation. You cannot define a macro within 
another macro definition. 

The MACRO Directive 

The MACRO assembler directive begins a macro definition. The format of the MACRO 
directive is: 

MACRO name ; comments here (optional) 



The name is a standard assembler symbol: a letter, optionally followed by one to seven 
alphabetic, numeric, dollar sign, underscore, or period characters. Since you use this name 
to invoke the macro, it is wise to choose a name that indicates the macro's function. 

The symbol chosen as the macro's name must be unique — it cannot be identical with any 
other symbol used within the assembler source file. 



The Macro Body 

The macro body is a sequence of assembler statements. Any statements, except the MACRO, 
ENDM, and END directives, may be included in the body. The statements can include 
processor instructions, assembler directives, invocations of other macros, or even 
invocations of the given macro. 

Comments and blank lines within the macro body are discarded, since they do not affect 
macro expansion. 

Macro Body Operators 

The macro body can contain special operators not available outside of macro definitions. 
These special operators give the macro access to assembler values, such as: 

• each parameter passed to the macro, 

© a unique character sequence for each macro invocation, 

• the number of parameters passed to the macro, and 

• the current section name. 

The following paragraphs describe these operators in detail. 
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Parameter Access ('1', '2', ...) 

The macro can access any parameter given when the macro is invoked. Parameters are 
identified with consecutive positive integers, starting at 1 for the leftmost parameter. Within 
the body of the macro, any number enclosed within single quotes is replaced with the 
corresponding parameter from the macro invocation line. For example, during macro 
expansion, any occurrence of T in the macro body is replaced with the first parameter. 

Text substitution can occur anywhere on the line, including text within the comment field. If 
text substitution causes the line to exceed 127 characters, an error is generated and the line 
truncated. Examples of text substitution can be found in the Macro Invocation subsection 
later in this section. 

The value within single quotes may be either a constant or a numeric-valued SET variable. 
Refer to the description of the SET directive in the Assembler Directives section of this 
manual for further information on numeric assembler variables. 

If the value within quotes is greater than the number of parameters actually provided, a null 
string is substituted at the time of expansion. 



Unique Label Generation (the @ Character) 

The "at" character, when enclosed within single quotes ('@'), is used to provide unique 
labels for each macro expansion. Each time a macro is invoked, the '@' construct is replaced 
with a unique four-character value. When this value is appended to a one-to-four character 
symbol within the macro body, a unique five-to-eight character label is created for each 
invocation. In the following example, a unique seven-character label is generated each time 
the macro is invoked. That label is used as the destination of a processor jump instruction: 

MACRO Q 

LAB'@' EQU $ 

JNZ LAB'@' 

ENDM 

If "LAB" had not been followed by the '@' construct in this example, the first invocation of 
macro Q would have defined the location of LAB. Any subsequent invocations would attempt 
to redefine the location of LAB, resulting in an error. 



Determining Parameter Count (the # Character) 

The "pound" character, when enclosed within single quotes ('#'), is replaced at time of 
expansion with a five-digit number. This number represents the total number of parameters 
passed to the current macro expansion. For example, if three parameters are passed to the 
macro, '#' is replaced with 00003 during macro expansion. 
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the macro to depend on the number of parameters passed. Examples of '#' usage are given in 



Determining Current Section Name (the % Character) 

The "percent" character, when enclosed within single quotes ('%'), is replaced by the name 
of the current section (as defined with the SECTION or COMMON assembler directives). The 
section name is given as a sequence of characters. If the current section is the default 
section, '%' is replaced with a null string. 

The '%' construct is usually used when the macro must define instructions or data in a new, 
distinct section, and then return back to the original section definition. To accomplish this 
task, the macro must save the name into an assembler string variable, change section 
names, give the declarations for the new section, and then use a RESUME directive to return 
to the original section, as illustrated in the following example: 

STRING SECNAME(8) ; Defines SECNAME as a string of up to 

; 8 characters 



MACRO Q ; Beginning of macro definition 

SECNAME SET itiflm . Save current section name in SECNAME 

SECTION QQ ; Switch to new section (QQ) 

RESUME 'SECNAME' ; Switch back to previous section 

ENDM ; End macro definition 

In the above example, the '%' construct is enclosed within double quotes. The SET directive 
expects a string expression, but the '%' construct is replaced with a sequence of characters. 
When this sequence of characters is enclosed within double quotes, it becomes a string 
literal, which is an acceptable string expression. 



Disabling Special Character Significance (the A Character) 

The up-arrow character (A), when immediately preceeding any special character, disables 
the special meaning of that character, and causes the character to be interpreted as part of 
the text. In the following example, the up-arrow character removes the special significance of 
the single-quote character: 

ASCII "That~'s all, folks!" 
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When the macro is expanded, the following text string is generated in the program: 

That's all, folks! 

The ENDM Directive 

The macro definition is terminated with the ENDM directive. This directive should not have a 
label field. 



MACRO INVOCATION 

A macro is invoked when its name appears in the operation field of an assembler line. For 
example, the macro QQQ is invoked by the following assembler statement: 

QQQ ; Comments (if used) go out here 



Parameters 

The macro body can make use of information given to the macro at the time of invocation. 
This information is given as a series of one or more parameters in the operand field of the 
macro invocation. Each parameter is a sequence of characters separated from other 
parameters by commas. For example, the following assembler statement invokes macro QQQ 
with parameters of 123 and ABC: 

QQQ 123, ABC ; Invokes macro QQQ 

; with parameters 123 and ABC 

As QQQ is expanded, any occurrence of.'V within the macro body is replaced with 123, and 
any occurrence of '2' is replaced with ABC. 

Any number of parameters can be passed to a macro, so long as the invocation line 
(including the comment) does not exceed 128 characters. Any parameters given in the 
invocation that are not examined within the body of the macro are simply ignored. Any 
parameter requested within the body but not given in the invocation is replaced with the null 
string. 

Macro Parameter Conventions 
The Square Brackets 

Any leading or trailing spaces surrounding a macro parameter are removed upon macro 
expansion. You may, however, force the spaces to be retained by placing the parameter 
within square brackets ([ ]). The square brackets group together all text within them as one 
parameter. The brackets themselves are removed during macro invocation. For example, 
invoking QQQ with the following assembler line defines the parameters listed below: 

QQQ ABC, DEF ,[GHI],[ JKL ], MNO PQR 
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The parameters are listed beiuw, surrounded by asterisks. The asterisks are not part Oi 
text, however, but are used here to show the leading and trailing spaces. 



Parameter 


'i ' 


= 


*ABC* 


Parameter 


t 2 » 


- 


*DEF* 


Parameter 


'3' 


= 


*GHI* 


Parameter 


'4' 


= 


* JKL * 


Parameter 


'5' 


= 


*MNO PQR* 



A parameter containing a comma must aiso be surrounded by brackets, or the parameter will 
be separated into two distinct parameters. For example, the invocation: 

QQQ ABC,DEF,[GHI,JKL] 

generates the following parameters (again, the asterisks are not part of the parameters): 

Parameter '1' = *ABC* 
Parameter '2 ? = *DEF* 
Parameter '3' = *GHI,JKL* 

Square brackets may not be nested. 



Double Quote Characters 

All text enclosed within double quote marks ("") is considered to be a single parameter. The 
quote marks are not removed from the text during macro expansion, but are considered as 
part of the parameter. For example, QQQ invoked with the assembler line: 

QQQ "ABC,"DEF,GHI" , " JKL ", "MNO" 

generates the following parameters (again, the asterisks are not part of the parameters): 

Parameter f 1 • = *»ABC"* 

Parameter '2' = *"DEF,GHI"* 

Parameter '3' = *" JKL "* 

Parameter '4' = *"MNO"» 

Square brackets can appear within parameters enclosed in quote marks; the brackets in this 
case are treated as normal text characters. Double quote marks can appear within a 
parameter surrounded by square brackets; the quote marks are then treated as normal text 
characters. For example, the macro invocation line: 

QQQ "A[B", [CD] , [ " 1 , "]" 

generates the following parameters upon expansion (again, the asterisks are not part of the 

parameters): 

Parameter '1 • = *"A[B"* 

Parameter '2 1 = »C"D« 

Parameter '3' = * " * 

Parameter '4' = *"]"* 



O 
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Null Parameters 

Two consecutive commas, or two commas separated only by blanks, define a null parameter. 
The parameter is counted in the total parameter count (for '#'), and returns a null string if 
requested in the body of the macro. For example, the macro invocation line: 

QQQ ABC,,DEF, ,GHI,[],JKL 



■ Null parameters 



generates the following parameters: 

•1 ' = *ABC* 
»2 ' = ** 

'3' = *DEF* 

•5' 
'6' 
'7' 



Parameter 
Parameter 
Parameter 
Parameter 
Parameter 
Parameter 
Parameter 



** 

*GHI* 
** 

*JKL* 



(Null parameter) 
(Null parameter) 
(Null parameter) 



Leading and trailing commas in the parameter list also generate null parameters, as in the 
following example: 

QQQ ,,ABC,, 

u 



Parameter 
Parameter 
Parameter 
Parameter 
Parameter 


'1 ' 
» 2 « 

•3' 
•5' 


= ** 

- ** 

= *ABC« 

- ** 

= ** 


Null parameters 

(Null parameter) 
(Null parameter) 

(Null parameter) 
(Null parameter) 



The Up- Arrow Character in Macro Invocations 

To include a special character in a macro parameter, the character must be immediately 
preceded by an up-arrow (A) character. The up-arrow character disables the special 
significance of any character, and is removed before the macro is expanded. For example, 
invoking QQQ with the assembler line: 

QQQ A%B , ~[CD~], ~"EF, G~~H, I~'J, K** A, L 

generates the following parameters: 



Parameter 


'1 ' 


= *A,B* 


Parameter 


'2' 


= »[CD3* 


Parameter 


,3, 


= *»EF* 


Parameter 


'14' 


= *G~H* 


Parameter 


•5' 


= *I'J* 


Parameter 


' D ' 


= *ir ; L* 
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Macro Examples 



MACRO EXAMPLES 

The examples in this subsection illustrate macro usage through typical macro definitions and 
expansions. 



Example 1: Simple Macro Invocation 

!n this example, macro QQQ is defined. QQQ contains two assembler statements: a BYTE 
directive and a WORD directive. The operands for these assembler statements are obtained 
from the parameters given with each invocation of QQQ. 

MACRO QQQ ; Beginning of definition 



BYTE 



WORD 



EN DM 



5, '1' ; BYTE directive, with a fixed operand 

; of 5, and an operand provided by the first 
; parameter of QQQ at invocation 

'2' ; WORD directive, with operand provided by 

; second parameter of QQQ at invocation 

; End of macro definition 



Invoking this macro with the following assembler statement: 

QQQ 35, 40 

produces the following sequence of assembler statments upon macro expansion: 



BYTE 
WORD 



5, 35 
40 



During expansion, each occurrence of '1 ' is replaced with 35 before the assembler statement 
is processed. Each occurrence of '2' is similarly replaced with 40. The resulting BYTE and 
WORD directives are then processed as if the assembler statements had been part of the 
original source text. 



Example 2: Nested Macro Invocations 

In this example, an assembler statement in the body of one macro invokes another macro. 

Beginning of Q1 definition 

Generate a word containing 
the first parameter, and a 
second word containing zero 

End of Q1 definition 

Beginning of Q2 definition 

Invoke Q1 with first parameter 
and again with second parameter 

ENDM ; End of Q2 definition 



MACRO 


Q1 


WORD 


•1 


ENDM 




MACRO 


Q2 


Q1 
Q1 


M 
•2 



(5) 
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Invoking Q2 with the following assembler statement: 

Q2 3, 5 

generates the following equivalent assembler source statements during the expansion 
process: 

WORD 3, 

WORD 5, 

The assembler performs the following steps during evaluation of the Q2 invocation line given 
above: 

• Q2 is invoked, with parameters of 3 and 5. 

• The first statement in the body of Q2 is examined. This statement contains a reference 
to the first parameter, so the appropriate parameter (the number 3) is substituted before 
proceeding. 

• The statement invokes macro Q1, with a parameter of 3. 

• Q1 is invoked, and the first (and only) statement of Q1 is examined. This statement 
contains a parameter reference, so the appropriate parameter (3) is substituted. 

• The resulting assembler statement (WORD 3, 0) is processed, generating two words of 
memory. 

• Expansion of Q1 terminates, and expansion of Q2 resumes with the second line in its 
body. 

• This line of Q2 has a reference to the second parameter, so the appropriate parameter 
(5) is substituted before further processing. 

• The assembler statement invokes Q1, with a parameter of 5. 

• Q1 is invoked as described above, resulting in the assembler statement " WORD 5,0". 

• When the expansion of Q1 is completed, expansion of Q2 resumes. 

• Q2 contains no further statements in its body, so expansion of Q2 also terminates. 



Example 3: Conditional Macro Expansion 

In this example, a macro expands one of two different ways, depending on whether one of its 
parameters is present of absent. Macro QQ generates three WORDs of its first parameter, 
followed by one WORD of its second parameter. If the second parameter does not exist (or is 
null), one word of 13 (decimal) follows the first three words. 

Beginning of definition 

Generate three words of the first parameter 

If the second parameter is null: 

generate a word of 13 
Else, (if the second parameter is not null) 

generate a word of the second parameter. 
Terminate the conditional assembly block 
Terminate the macro definition 



MACRO 


QQ 




WORD 


M', '1' , 


1 1 ' ; 


IF 


II IOt II _ II II 




WORD 


13 




ELSE 






WORD 


'2' 




ENDIF 






ENDM 
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generates the following assembler statements: 



WORD 
WORD 



5, 5, 5 
24 



Invoking this macro with the following assembler statement: 

QQ 7 

produces the following sequence of assembler statements: 



WORD 
WORD 



7, 7, 7 
13 



In the first invocation, both parameters are specified. During the expansion of QQ, the IF 
directive substitutes the appropriate parameter and evaluates the expression "24"="". This 
expression is false, and the statements between the IF statement and the ELSE statement 
are skipped. 

In the second invocation, the expression at the IF statement reduces to ""="". This 
expression is true, so the assembler statements between the IF and ELSE are processed, and 
the statement between the ELSE and ENDIF is skipped. 



Example 4: Repetitive Macro Expansion 

In this example, a macro performs a single operation on each of its parameters. The macro 
contains a REPEAT.. ENDR loop that is controlled by the '#' value. 

Beginning of macro definition 



MACRO BACK 
PARMCNT SET 1 

REPEAT PARMCNT<='#' 



BYTE 
BYTE 



PARMCNT SET 
ENDR 
EN DM 



HI( 'PARMCNT' ) 
LOC PARMCNT') 



PARMCNT+1 



Initialize the parameter counter 

Repeat the following group of 
assembler statements while the 
current parameter count is less 
than or equal to the total number 
of parameters 

Store the high byte 

followed by the low byte of the 

selected parameter 

Advance to the next parameter 

and repeat as necessary 

End of BACK definition 



(a) 
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Macro BACK takes each of its parameters (one at a time), and generates two bytes for that 
parameter: the most significant byte of the parameter, followed by the the least significant 
byte. For example, the assembler statement: 

BACK 25, 26, 27, LAB 

generates the following assembler statements during the expansion of BACK: 



BYTE 


HI (25) 


BYTE 


LO(25) 


BYTE 


HK26) 


BYTE 


L0(26) 


BYTE 


HK27) 


BYTE 


LO(27) 


BYTE 


HI(LAB) 


BYTE 


LO(LAB) 



The assembler performs the following operations during this expansion of BACK: 

• BACK is invoked with the indicated parameters. 

• The assembler variable PARMCNT is initialized to 1 . PARMCNT always contains the 
number of the parameter currently being processed. 

• The REPEAT loop is entered. The expression PARMCNT<='#' is expanded to 
PARMCNT<=4, since the total parameter number is 4. This expression is true (1 is less 
than 4), so the body of the REPEAT loop is evaluated. 

• The assembler directive BYTE Hl(' PARMCNT') is expanded to BYTE Hl(25). PARMCNT 
contains 1, so the first parameter is substituted for 'PARMCNT'. This assembler 
directive is then processed. 

• In a similar manner, BYTE LO('PARMCNT') is expanded and processed. 

• To select the second parameter, PARMCNT is incremented by one. 

• The REPEAT loop is processed again, with PARMCNT equal to 2 (selecting the second 
parameter of 26). At the end of the loop, PARMCNT is incremented once again to 3. 

• The REPEAT loop is processed once again, generating bytes for the third parameter (27). 
PARMCNT is again incremented. 

• The REPEAT loop is processed once more, generating bytes for the fourth (and last) 
parameter, LAB. PARMCNT is incremented, and now contains the value 5. 

• The expression of the REPEAT loop, PARMCNT<='#', is no longer true, since PARMCNT 
(5) is now greater than 4 (the total parameter count). The statements within the REPEAT 
loop are skipped, and processing continues after the ENDR statement. 

• Expansion of BACK terminates, because no more statements remain to be processed. 
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Section 7 
THE LINKER 



INTRODUCTION 

The iinker merges one or more independentiy-assembied object fiies into a ioad fiie, suitable 
for loading into memory. Linker input may come from the assembler, or from library files. 
(See the Library Generator section of this manual for further information on library files.) 

This section describes the operations and use of the linker, and is divided into the following 
subsections: 

• Linker Invocation. Describes how you invoke the linker, using the TEKDOS LINK 
command. 

• Linker Execution. Describes operations performed by the linker. 

• Linker Output. Describes the listing file generated by the linker. 

• Linker Commands. Presents a detailed description of each command used to control 
the operation of the linker. 

Some typical uses of the linker are presented in the Operating Procedures and Programming 
Examples sections of this manual. 

LINKER INVOCATION 

You may invoke the linker by one of the following three methods: 

• Simple Invocation: Requires you to specify only the input and output filenames. Other 
linker parameters are set to default values. This method is adequate for most linking 
situations. 

• Interactive Invocation: Allows you to control the linker more precisely using a series of 
commands. These commands define global symbols, listing content, and linker 
parameters, and specify section attributes and location. The commands used in 
interactive invocation are given later in this section. 

• Command File Invocation: Allows you to place commands normally given in interactive 
invocation into a file. You can then direct the linker to process those commands when 
you specify only the filename. 

Command file invocation is helpful whenever a particular sequence of linker 
commands must be used more than once. The sequence of commands can be entered 
once to a disc file, then processed many times by the linker. If you invoke the linker 
from a TEKDOS command file, and simple invocation of the linker will not suffice, then 
command file invocation can be used. In this case, interactive invocation requires you 
to be present during the linker's execution; this is generally not true in normal use of 
TEKDOS command files. 

The method of invocation that you choose will depend on the linking situation. Each type of 
invocation is described in detail in the following pages. 
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Simple Invocation 



SYNTAX 

isc-drive]| 
LINK [load-file[/disc-drive]] [list-device J lobject-file[/disc-drive] 



[list-file[/disc-drivef| JLIB(library-file[/disc-drive]) 
list- device J 



PARAMETERS 

load-file The name assigned to the linker-created load file. 

disc-drive A disc drive number. If the drive number is omitted, then the current 

system drive is used. 

list-file The name assigned to the linker listing file. 

list-device The name of the device (LPT1, CONO, etc.) that receives the linker 

listing file. 

object-file The name of an object file to be linked. 

library-file The name of a library file to be linked. 

EXPLANATION 

In simple linker invocation, you specify all input and output files in a single command line. 
The one or more object and library files are linked together to produce the load file. The 
linker's listing can be directed to a device or file, also specified in the command line. 

EXAMPLES 

LINK MYPROG;L MYPR0G;K/1 MYPROG;0 

This invocation line links the object file MYPROG;0 on the system drive to produce the load 
file MYPROG;L on the system drive and listing file MYPROG;K on drive 1. 

LINK,,LPT1 MYPR01;0 MYPR02;0 
This invocation line links MYPR01;0 and MYPR02;0 (both on the system drive), generating a 
listing on the line printer (LPT1). No load file is generated. 

LINK MYPR;L/1 MYPR;K/1 MYPR1;0/1 MYPR2;0/1 LIB(LIBRAR ;Y/0) 

This invocation line links object files MYPR1;0 and MYPR2;0 (both on drive 1) to produce 
listing file MYPR;K and load file MYPR;L (both on drive 1 ). If any unbound (undefined) globals 
remain after the two object files are linked, the linker will search through library file 
LIBRAR;Y (on drive 0) for definitions of these unbound globals. 
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Linker invocation (interactive) 



Interactive invocation 



SYNTAX 



LINK 



EXPLANATION 



When you enter the LINK command without any parameters, the linker is invoked in 
interactive mode. The linker displays a prompt character (an asterisk), and waits for you to 
enter a series of linker commands. When you enter the linker END command, the linker 
processes the files you have specified in a linker LINK, LIST, or LOAD command line. 

Linker commands are fully described in the Linker Commands subsection (later in this 
section). 

NOTE 

The TEKDOS LINK command (described here) invokes the linker. The linker 
also has a command called LINK, which specifies a series of input files to the 
linker; that command is described in the Linker Commands subsection of this 
section. These two commands have distinctly different functions, and should 
not be confused. 
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Command File Invocation 



SYNTAX 



LINK 



I@command-device-name 
@command-file-name[/disc-drive] 



PARAMETERS 



command-device- The input device (CONI, PPTR, etc.) from which the linker will read a 

name series of commands. 

command-file-name The name of a disc file from which the linker will read a series of 
commands. 



disc-drive 



A disc drive number. If the drive number is omitted, the current 
system drive is selected. 



EXPLANATION 



This type of linker invocation is similar to interactive invocation, but commands are read from 
the designated file or device, rather than from the system terminal. Commands are taken 
from the file (or device) until the END command is read, or the end of the file is reached 
(whichever comes first). 



EXAMPLES 



LINK 0LCFILE/1 

This invocation line executes the linker commands contained within disc file LCFILE on drive 
1. 
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LINKER EXECUTION 

A program consists of one or more object modules. Each object module contains one or more 
sections. Each section is an independent entity: a contiguous block of instructions and data 
that will eventually be located somewhere in memory. The linker derives the final position of 
each section in accordance with the attributes of the section. These section attributes, 
provided in the object module by the assembler, are described in the following paragraphs. 

NOTE 

Throughout this discussion, "section" (in lowercase) refers to an assembler- 
generated SECTION, COMMON, or RESERVE program/data block. 
"SECTION" (all uppercase) refers only to a program/data block generated 
with the SECTION assembler directive. 



Section Attributes 

Every section has five attributes that provide the linker with the necessary memory allocation 
information. These section attributes are name, section type, size, relocation type, and 
memory location. 

Name: Each section has a name of up to eight characters. The name is 

assigned to the section with a SECTION, COMMON, or RESERVE 
assembler directive. The section name can be used as a global symbol to 
reference the first memory address of a section. 

Section type: Each section is of type SECTION, COMMON, or RESERVE, as defined by 

the corresponding assembler directive. 

Each SECTION must have a unique name. Multiple SECTIONS having 
the same name are flagged as errors. 

All COMMON sections having the same name are allocated the same 
space and beginning address in memory. The length of this memory 
space is the size of the largest COMMON section of this name. 

All RESERVE sections having the same name are concatenated by the 
linker. The length of a given RESERVE section in the program is the sum 
of all RESERVE sections having that same name. 

Size: The size of each section, determined at assembly time, is the total 

number of memory bytes that the instructions or data of the section 
must occupy. 
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Relocation type: 



Memory location: 



Each section has one of four relocation types: byte-relocatable, inpage- 
relocatable, page-relocatable, or absolute (non-relocatable). 

Byte-relocatable sections may be placed anywhere within the 
microprocessor address space. 

Inpage-relocatable sections are placed entirely within a microprocessor 
page. The length of the page is microprocessor-specific. Page length for 
each microprocessor is given in the corresponding Assembler Specifics 
section elsewhere in this manual. If an inpage-relocatable section 
exceeds one page in length, the linker displays an error, redefines the 
relocation type of the section to be page-relocatable, and continues the 
linking process. 

Page-relocatable sections begin on a page boundary (an integral 
multiple of the page length). 

Absolute sections are not relocated by the linker. Their position in 
memory is determined at assembly time through the use of the ORG 
directive. If two absolute sections are both designated by the assembler 
for the same memory area, the linker notes this conflict on the memory 
map, and the contents of this memory area are undefined. 

The memory location of all absolute sections is defined at assembly 
time. For relocatable sections, a beginning address or range of 
addresses may be specified with the LOCATE command at link time. The 
default address range for a relocatable section is the entire 
microprocessor addressing space. 



Allocation of Sections 

The linker computes an address range for each section to exclusively occupy in the linked 
program. Sections with more restrictive relocation types are given the first opportunity to 
obtain their required addresses. For example, an absolute section is allocated its (very) 
restrictive address range before any relocatable section is linked. The precise order of linking 
is as follows: 

1 . Absolute sections. 

2. Based sections: any sections defined with the BASE attribute in the linker LOCATE 
command. 

3. Ranged page-relocatable sections: any page-relocatable sections further restricted 
with a RANGE, as specified with the linker LOCATE command. 

4. Ranged inpage-relocatable sections. 

5. Ranged byte-relocatable sections. 

6. Page-relocatable sections. 

7. Inpage-relocatable sections. 

8. Byte-relocatable sections. 
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vvnen a memory location ior a section is being chosen by the linker, the lowest memory 
address range that meets the relocation requirements (as well as addition restrictions 
presented in the LOCATE command) will be allocated to the section. For example, if the 
program consists only of 10 byte-relocatable sections, all 10 sections will be located in a 
contiguous block of memory starting at 0000. 

Absolute and based sections are linked even if a conflict occurs (that is, when two or more 
sections have bytes at the same address). Any conflicts are noted on the linker memory map. 
Other section types are not linked if a conflict occurs. In any memory area where conflict has 
occurred, the contents are undefined. 

Normally, the instructions and data for a section, define a contiguous block of bytes in 
memory. However, some absolute sections of the program can be discontinuous as a result 
of the assembler ORG directive. Such sections define instructions and data for non- 
consecutive bytes of memory. The linker recognizes the gaps between the instructions/data 
of the section, and places other (relocatable) sections in these gaps. For example, if the 
assembler statement " ORG $+128" is present in an absolute section at assembly time, a gap 
of 128 (decimal) bytes is created within that section. The linker can then place any 
combination of relocatable sections into this gap, as long as the total number of bytes taken 
does not exceed 128. 



ENDREL 

ENDREL is a predefined global symbol. At link time, ENDREL is assigned the memory address 
that is one higher than the highest memory address assigned to any relocatable section (not 
absolute or based). Be aware that some absolute or based sections may be allocated memory 
that is higher than the address given by ENDREL. 

If you do not reference ENDREL, no value is assigned. If you define a value for ENDREL, your 
value will take precedence over the predefined value. 



Linking a Library File 

If any undefined global symbols remain in the linker's global symbol table, and a library file 
has been specified, the linker examines the library file to determine if some or all of the 
undefined globals are defined in one of the library modules within that file. 

Each module in the library contains a list of all global symbols defined within that module. 
Global symbols include section names, addresses within sections, and scalar values declared 
global at assembly time. 

When a definition is found within a library module for an undefined global symbol, then that 
entire module is linked along with all other object modules. Only the modules that provide 
needed definitions for global symbols are linked; the rest are simply skipped. 
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The linker processes files in the order that the files are specified. If an object file requires 
that a library module be linked, you must specify the object file first. If a library file were to be 
specified first in a linker invocation, none of the library modules would be linked; when the 
linker processes the library, the global symbol table contains no undefined entries, causing 
the linker to skip the library. In general, the safest way to specify files in the command line is 
to list all object files before all library files. 

Further information about libraries can be found in the Library Generator section of this 
manual. 



LINKER OUTPUT 

The linker generates two files. The load file contains the executable program instructions 
and data. The load file can be loaded into 8002A Program Memory with the TEKDOS LOAD 
command. The listing file contains a summary of the actions performed by the linker. Either 
of these files can be omitted in any linker invocation. The listing file is described in the 
following paragraphs. 



Listing File 

The listing file summarizes the operations performed during the linking process. The listing 
file can be directed to any output device or disc file. The following information is included in 
the linker listing file: 





Simple Invocation 


Interactive Invocation 


Global Symbol List 

Internal Symbol List 

Map 

Linker Statistics 

Error Messages 


Yes 

If selected in assembler 

Yes 

Yes 

If necessary 


Yes 

If selected in assembler 

If selected 

Yes 

If necessary 



Each of these listing items is described in the following paragraphs. 

NOTE 

Throughout this subsection, annotations are added to the listing samples to 
aid your understanding. These annotations are enclosed in square brackets 
([]), and are not generated by the linker. 
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Linker Output 



Globa! Symbol List 

The global symbol list contains an alphabetic list of all global symbols and their values. These 
giobai symbois inciucie those symbols defined with the assembler GLOBAL directive, as weil 
as the names of SECTION, COMMON, and RESERVE sections. If a global symbol is 
undefined, its value field contains asterisks. In the following example, the global symbol QQQ 
is undefined, but was referenced by one or more object files. 



TEKTRONIX 8080/8085 LINKER V x .x 



GLOBAL SYMBOL LIST 



Q1 1000 Q2 0500 QQQ **** X1SECT 

X2 SECTA 045F X2 SECTB 0640 [QQQ is undefined] 



PAGE 
0060 



internal Symbol List 

The internal symbol list contains all symbols (other than strings and macros) defined in the 
assembler source file, along with their actual values after relocation. The internal symbol list 
parallels the assembler symbol table listing for the selected file. The list consists of three 
parts: 

1 . Alphabetical list of scalars used in the assembly. 

2. Alphabetical list of labels occurring within each section. 

3. Alphabetical list of labels derived from each unbound global symbol. 

If there are no labels for a section, or no labels derived from an unbound global, then that 
section or unbound global is not indicated. 



A sample internal symbol list follows. 
TEKTRONIX 8080/8085 LINKER V x.x 
FILE: QQ ; /0 [input file name] 



INTERNAL SYMBOL LIST PAGE 



0000 


C 


0001 


D 


0002 


0004 


L 


0005 


M 


0006 


0500 


R1 


1E00 


SP 


0006 


0030 











MODULE : I0_DR VR [name assigned with the assembler NAME directive] 

SCALARS: [non -address symbols] 

A 0007 B 

E 0003 H 

PSW 0006 Q2 

X1 VALUE 007F X2VALUE 

LABELS: (SECTION I0_AREA ) [all address symbols within section IQ.AREA] 

L1 0T00 L2 0130 

LABELS: (SECTION I0_AREA2) [all address symbols within section IO_AREA] 

Q1 0150 Q2 0155 

LABELS: (GLOBAL I0_P0RT ) [all symbols derived from global IQ_PORT] 

10 P0RT1 0070 10 P0RT2 0071 



The internal symbol list is displayed only for those object modules that were generated with 
the LIST DBG assembler option. Refer to the Assembler Directives section of this manual for 
further information about the LIST directive. 
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Map 

The map consists of two parts: a moduje map, and a memory map. The map is included in the 
listing file only if the linker MAP command has been specified. 

A module map lists all modules linked into the load file. The module map contains 
information about sections and global symbols defined in each object module. 



TEKTRONIX 8080/8085 LINKER V x.x 



MODULE MAP 



PAGE 



FILE: FILE1;0/0 [input file name, as specified in LINK command] 
MODULE : MAINMOD [module name, from assembler NAME directive] 



D0_I0 SECTION BYTE 3700-3E40 

INPUT 3A00 OUTPUT 3B50 

MAINPROG SECTION BYTE 3E41-5141 

ENTRY1 4091 ENTRY2 43A1 

STACK RESERVE PAGE 3600-36FF 



[a byte-relocatable SECTION] 
[globals defined within this section] 
[another byte- relocatable SECTION] 
[globals defined within this section] 
[a page-relocatable RESERVE section] 



FILE: FILE2;0/1 [end of first file, beginning of second file] 

MODULE: SUBMOD [module name, from assembler NAME directive] 

ABSECT2 SECTION ABSOLUTE 0040-0357 [absolute SECTION] 

ENTRY3 0090 [global address within section] 

RELSECT2 SECTION PAGE 0400-2400 [page-relocatable SECTION] 

ENTRY4 0450 [global address within section] 

FILE: FILE3;0/1 [end of second file, beginning of third file] 

MODULE: SUBS2M0D [module name] 

RELSECT3 SECTION PAGE 2500-3500 [a page-relocatable SECTION] 

The module map lists all linked modules. An alphabetical list of sections and entry points 
(globals defined within each section) is included for each module. If no sections were linked 
in a module, no room for a section exists, or a section is empty, an appropriate message is 
included in the module map. 

A memory map is an ordered listing of the memory allocated to sections. The list starts With 
the lowest allocated address and continues to the highest allocated address. For every 
address range, each section name and its attributes are given. An example of a typical 
memory map follows: 



TEKTRONIX 8080/8085 LINKER V x .x 
[beginning-ending address] 

[section name] 

[section type] 



MEMORY MAP 



PAGE 



0040-0357 
0400-2400 
2500-3500 
3600-36FF 
3700-3E40 
3E4A-5141 



ABSECT2 

RELSECT2 

RELSECT3 

STACK 

DO 10 

MATNPR0G 



[relocation type] 




SECTION ABSOLUTE 
SECTION PAGE 
SECTION PAGE 
RESERVE PAGE 
SECTION BYTE 
SECTION BYTE 
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asterisk (*) following the address range in which the conflict occurs. 



Linker Statistics 

The linker statistics give the number of errors, undefined symbols, modules, sections, and 
the transfer address. 

NO ERRORS NO UNDEFINED SYMBOLS 

3 MODULES 6 SECTIONS 

TRANSFER ADDRESS IS 3E4A 

The transfer address identifies the program starting location. After loading this example 
program, you could start execution by entering the TEKDOS command "GO 3E4A". 



Error Messages 

Error messages are issued wherever necessary. Three types of error messages can appear: 

1 . Warnings (W): A problem exists but the linked program can probably be executed. 

2. Errors (E): A linked program probably will not execute properly. 

3. Fatal Errors (F): Any error directly affecting the linker's ability to continue; the linker 
terminates execution, and control returns to TEKDOS. 

All errors cause a message to be displayed in the linker listing file and on the system 
terminal. 

In the following list, each error message is indicated as being a warning (W), error (E), or fatal 
error (F). 

ATTEMPT TO RE-DEFINE FILE TYPE FOR filename. (W) filename was specified twice: 
once as an object file, and once as a library file. The linker uses the first file type specified. 



idname I/O ERROR #nn. (E) The linker was unable to read from or write to idname (either 
LIST FILE, LOAD FILE, CONSOLE, COMMAND FILE, or OBJECT FILE). The error number is 
the corresponding TEKDOS SVC (service call) SRB status byte. Refer to the Error Codes 
section of the 8002A System Users Manual for a description of the error. 



IMPLICIT REORIGIN TO IN SECTION sec IN MODULE mod FILE file. (W) A section has 
wrapped around from the last memory location to location 0. 
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INVALID OBJECT CODE FORMAT FOR FILE filename LOCATION = nnnn. (E) The 

information contained within the file is not an object module. Verify that the designated 
object file has been generated by the assembler, or that LIB( ) surrounds the library filename. 
nnnn indicates the internal linker address where the object file error was detected. 



LINKER INTERNAL ERROR AT nnnn. (E) An error occurred in the linker; try linking again. 
If this error persists, carefully document the incident and submit an LDP Software 
Performance Report to Tektronix. 



MACHINE REDEFINED FROM processor IN MODULE mod FILE file. (W) The current 
object module has been generated for a different microprocessor than the previous object 
modules. Incompatibilities during linking may result from differences between 
microprocessors, such as page length, byte order, etc. 



MEMORY FULL. (E) The linker requires more memory to complete its task. The total number 
of globals, sections, or object modules must be reduced in order to link in the available 
memory. 



NO ROOM IN RANGE mmmm-nnnn FOR SECTION sectname. (E) The length of the 
indicated section is greater than available contiguous memory in range mmmm-nnnn of 
allocated section memory. 



RELOCATION TYPE OF SECTION sec MULTIPLY DEFINED IN MODULE mod FILE fin. 

(W) An attempt was made to redefine the section relocation type (byte, page, inpage, or 
absolute). This occurs when you use the LOCATE command to define a relocation type 
different from the type specified at assembly time. The error also occurs when relocation 
attributes of a COMMON or RESERVE section differ between modules. The linker uses the 
first-encountered relocation attribute to define the section. 



SECTION sectname CHANGED FROM INPAGE TO type RELOCATABLE. (W) Section 
length is greater than the page size of the microprocessor. This can occur if several inpage 
RESERVE sections are linked together and their total size exceeds the page size of the 
microprocessor. A section declared to be inpage-relocatable in a LOCATE linker command 
generates this error if the section exceeds microprocessor page size, type is replaced with 
PAGE for sections smaller than available page size, or BYTE for sections larger than the 
microprocessor page size. 
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declared to be page-relocatable and the linker does not support paging for the 
microprocessor; or there was insuiiiCient room ior a pageu section in avahau'e memory, m 
either case, the relocation type is changed to byte-relocatable. 



SECTION sectname EXCEEDS MAXIMUM SIZE. (E) Section length is greater than the 
address space of the microprocessor. The section is not included in the load file. This error 
may occur when a concatenated RESERVE section is too long. 



symbolname MULTIPLY DEFINED IN MODULE modname FILE filename. (E) An attempt 
was made to redefine a global symbol or section. This error occurs when two modules define 
a global or section of the same name. All section names must be unique. The linker uses only 
the first definition of a section or global symbol in the load file. 



TRANSFER ADDRESS MULTIPLY DEFINED IN MODULE mod FILE file. (W)The module 
has attempted to define the transfer address when an address has already been provided 
(either by another module or by the linker TRANSFER command). The linker uses the first- 
encountered transfer address to generate a transfer address for the load file. 



TRANSFER ADDRESS UNDEFINED. (W) The transfer address has not been provided for 
this program. The transfer address can be provided either by a linker TRANSFER command, 
or as the optional expression value in an assembler END directive. When no transfer address 
is specified, the linker substitutes a transfer address of 0000. 



TRUNCATION ERROR AT nnnn IN MODULE mod FILE file. (W) The relocated value 
computed for a byte is too large to fit in one byte. 



UNABLE TO ASSIGN name. (E) The file or device name specified as an object or library file 
does not exist, or the output device is unavailable. 



UNRESOLVED REFERENCE AT nnnn MODULE modname FILE filename. (E) A reference 
to an unbound (undefined) global or section is specified at address nnnn in the object 
module. This error occurs when a global symbol is used in a module but not defined. The 
referenced symbol appears in the linker global syrnboi nst with an uriueiined vaiueonuicateu 
by asterisks), and the unresolved reference is filled with zeros in the load file. 
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LINKER COMMANDS 

Linker commands are used when you invoke the linker interactively or with a command file. 
Each linker command must be on a separate line. 

In the following command descriptions, the same conventions are used as described in the 
Assembler Introduction section of this manual. 

NOTE 
All commands must be entered in their given form. Commands may not be 
abbreviated. 
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Linker Command: @filename 

Invokes a linker command file 



SYNTAX 



@filename[/disc-drive] 



PARAMETERS 



filename 



The name of the command file containing a sequence of linker 
commands. 



disc-drive 



The disc drive number on which the command file resides. If the drive 
number is omitted, the current system drive is used. 



EXPLANATION 



This command invokes filename as a command file. The command file contains a series of 
linker commands. Commands are read from the file and processed as if you had entered 
them from the system terminal, until the END command is read or the end of file is reached. 
Commands are echoed on the system terminal as they are processed. When the end of the 
command file is reached, you will be prompted for additional linker commands. Nested 
command files are not allowed: a command file may not invoke another command file. 



EXAMPLES 



6LINKIT/1 

This linker command invokes command file LINKIT (on drive 1). Additional linker commands 
will be read from file LINKIT and processed, until the end of file is reached, or until an END 
command within LINKIT is processed. 
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Gives value to global symbol 



SYNTAX 



DEFINE symbol=value[.symbol=value]. 



PARAMETERS 



symbol 



value 



A global symbol. 

A hexadecimal constant. 



EXPLANATION 



The DEFINE command assigns values to selected global symbols. Each symbol is entered into 
the global symbol table and assigned the corresponding value. Even if the global symbol was 
previously defined (by an object module), the value you specify in a DEFINE command 
replaces the already-defined value. 



EXAMPLES 

DEFINE XXX=400, YYY=1FFF, I0_P0RT=3E 
This DEFINE command gives values to the global symbols XXX, YYY, and IO_PORT. 
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Linker Command: END 

Signals end of linker command sequence 



SYNTAX 



END 



EXPLANATION 



The END command signals the end of the command sequence. You enter this command to 
start the linking process after you have completed entering all other linker commands. 

This command must be used in interactive invocation, but can be omitted for command file 
invocation. If END is omitted in command file invocation, the linker begins the linking process 
when the end of the command file is reached. 



@ 
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SYNTAX 



JLIB(library-file[/disc-drive])J r,LIB(library-file[/disc-drive]f| 
LINK |object-file[/disc-drive] J |_,object-file[/disc-drive] J 



PARAMETERS 

object-file The name of an object file to be linked, 

library-file The name of a library file to be linked. 

disc-drive A disc drive number. If the drive number is omitted, the current system 

drive is used. 

EXPLANATION 

The LINK command designates the input object and library files that make up the program. 

More than one LINK command can be specified in a sequence of linker commands. 
Successive LINK commands specify additional object and library files. For example, the 
command "LINK A, B, C" is identical in function to the command "LINK A" followed by 
commands "LINK B" and "LINK C". 

NOTE 

The linker LINK command (described here) specifies a series of input files to 
the linker. TEKDOS also has a command called LINK, which invokes the 
linker; that TEKDOS command is described earlier in this section under 
"Linker Invocation." These two commands (both called LINK) have distinctly 
different functions, and should not be confused. 

EXAMPLES 

LINK MYPR0G;0/1 
This command selects object file MYPROG;0 on drive 1 to be linked. 

LINK MYPR01;0/1, MYPR02;0 

This command specifies object files MYPR01;0 on drive 1 and MYPR02;0 on the system 
drive to be linked. 

LINK MYPR0G;0/1, LIB(LIBRAR ;Y/0 ) 

This command specifies object file MYPROG;0 on drive 1 to be linked. If the object module 
within MYPROG;0 contains any unbound global symbols, the linker searches through library 
file LIBRAR;Y on drive for definitions of those symbols. 
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Linker Command: LIST 

Designates listing file 



SYNTAX 



1 output-device-name \ 
f ilename[/disc-drive] J 



PARAMETERS 



output-device-name The name of an output device on which the linker listing will be 
displayed. 



filename 
disc-drive 



The name of the linker listing file. 

The disc drive number on which the listing file resides. If the drive 
number is omitted, the system drive is used. 



EXPLANATION 



The LIST command designates the file or device that is used for the linker listing. The 
contents of the listing file are described earlier in this section under "Linker Output." 



EXAMPLES 

LIST LPT1 
This LIST command designates the line printer (LPT1) to receive the linker listing. 

LIST MYPROG;K 

This LIST command designates disc file MYPROG;K (on the system drive) to receive the linker 
listing. 



@ 
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SYNTAX 



LOAD filename[/disc-drive] 



PARAMETERS 



filename 
disc-drive 



The name of the output load file. 

The disc drive number on which the load file resides. If the drive number 
is omitted, the current system drive is used. 



EXPLANATION 



The LOAD command designates the output disc file that receives the linked program. After 
linking, the file designated by the linker LOAD command may be brought into program 
memory, using the TEKDOS LOAD command. 



EXAMPLES 

LOAD MYPR0G;L/1 
This LOAD command designates MYPROG;L on drive 1 to receive the linked program. 

NOTE 

The linker LOAD command (described here) specifies the output file that 
contains the program after linking. TEKDOS also has a command called 
LOAD, which transfers a disc file into program memory; that TEKDOS 
command is described in the 8002A System Users Manual. These two 
commands (both called LOAD) have distinctly different functions, and should 
not be confused. 
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Linker Command: LOCATE 



Changes section attributes 



LOCATE section-name 



SYNTAX 

,BASE(starting-address) 
_,RANGE(starting-address,ending-address) 



,PAGE 

JNPAGE 

,BYTE 



section-name 

starting-address 

ending-address 



PARAMETERS 

The name of any section contained within the input object modules. 
A hexadecimal number representing a starting address. 
A hexadecimal number representing an ending address. 



EXPLANATION 

The LOCATE command alters the attributes of a SECTION, COMMON, or RESERVE section. 
The BASE parameter designates that the section should begin at the specified address. The 
RANGE parameter directs the linker to place the section anywhere within the given address 
range, as long as the beginning and ending addresses of the section lie within that range, 
and the location conforms to the relocation attribute (byte, inpage, page, or absolute). 

The PAGE, INPAGE, or BYTE parameter redefines the relocation type of the designated 
section. When you redefine the relocation type of a section, the linked code may execute 
differently than you intended. Certain portions of the code may expect or require that a 
section of code be located in a particular memory location type (on a page boundary, within a 
page, etc.). Whenever you use the PAGE, INPAGE, or BYTE parameter, and the relocation 
type differs from the type given to the section at assembly time, the linker will generate a 
warning message. 

EXAMPLES 

LOCATE MYSEC.A, RANGE (2000, 2FFF) 

This command informs the linker that section MYSEC.A should be placed entirely within the 
range of 2000 to 2FFF (hexadecimal). If MYSEC.A is longer than 4096 bytes, or MYSEC.A 
cannot be located in the designated area, an error is generated. 

LOCATE MYSEC.B, BASE(4000) 
This linker command designates that MYSEC.B begins at memory location 4000. 

LOCATE MYSEC.C, PAGE 
This linker command redefines MYSEC.C to be page-boundary relocatable. The linker will 
attempt to place the first address of MYSEC.C at a page boundary. A warning message will 
be displayed if MYSEC.C was not defined to be page-relocatable at assembly time. 

LOCATE MYSEC.D, RANGE (8000, FFFF) , BYTE 
This linker command designates that MYSEC.D will be placed somewhere in the upper 32K 
of memory, and redefines MYSEC.D to be byte-relocatable. 



@ 
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SYNTAX 



LOG 



EXPLANATION 



The LOG command causes all subsequent linker commands to be recorded (logged) in the 
linker listing file. 

The NOLOG command restores the default setting: commands are not recorded in the linker 
listing file. 
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Linker Command: MAP 

Includes map in listing 



SYNTAX 



MAP 



EXPLANATION 



The MAP command causes the map to be included in the linker listing file. Refer to the 
description of the map in the Linker Output subsection earlier in this section. 

The NOMAP command restores the default setting: the map is not included in the linker 
listing file. 
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SYNTAX 



NOLOG 



EXPLANATION 



The NOLOG command disables the recording (logging) of linker commands in the linker 
iisting file. Refer to the LOG command description for further information. 
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Linker Command: NOMAP 

Does not include map in listing 



SYNTAX 



NOMAP 



EXPLANATION 



The NOMAP command restores the default map setting: the map is not included in the linker 
listing file. Refer to the description of the MAP command for further information. 



@ 
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SYNTAX 



I global-symboll 
value j 



PARAMETERS 



global-symbol A symbol appearing in the global symbol table. 

value A one- to five- digit hexadecimal value that must begin with a digit (0 to 

9). 



EXPLANATION 

The TRANSFER command defines the load file transfer address. The transfer address 
designates the address of the first instruction to be executed when the program is run. This 
address is displayed when the program is loaded into memory, and is used as the default 
starting address when the TEKDOS GO command is entered without an address parameter. 

The transfer address can either be a fixed value (given as a hexadecimal address) or a global 
symbol. If a global symbol is designated, the transfer address will be taken from the symbol's 
value after linking. 

The transfer address may have been given at assembly time by placing an expression after 
the END statement. If a transfer address is selected at assembly time, and the TRANSFER 
command is used at link time, the address specified in the TRANSFER command takes 
precedence. 



EXAMPLES 



TRANSFER 400 

This linker command designates address 400 (hexadecimal) as the location of the first 
instruction to be executed. 

TRANSFER MY. START 

This command designates the value of the global symbol MY. START as the transfer address. 
When linking is completed, the value of MY. START is taken from the global symbol table and 
designated as the transfer address. 
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Command Processing Errors 

If the linker detects an error during command entry, an up-arrow (A) is displayed below the 
line, to indicate the approximate iocation of the error within the command iine. A message 
defining the error is also displayed. These messages are described in the following 
paragraphs. 



EXTRANEOUS INFORMATION IGNORED. Extra characters are on a command line that 
only requires an instruction (like LOG and MAP). The linker performs the appropriate action 
for the command, and ignores the extra characters. 



ILLEGAL COMMAND. The command was not recognized. 



INDIRECT FILE DEPTH EXCEEDED. A linker @filename command was found during the 
processing of a command file. The command is ignored. 



INVALID FILE NAME. The file specified in a LIST, LOAD, or LINK command contains illegal 
file characters. Refer to the File Management section of the 8002A System Users Manual for 
information on valid filenames. 



INVALID RANGE SPECIFIED. The range in a LOCATE command is invalid. The ending 
address must be greater than the starting address. 



SYNTAX ERROR. Statement syntax is invalid. This error occurs when a command does not 
precisely match the syntax for that command. For example, unmatched parentheses are 
found in the LOCATE command, or an operand is missing after the equals sign in a DEFINE 
command. 
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Section 8 
THE LIBRARY GENERATOR 



INTRODUCTION 

The library generator (LibGen) is a generai-purpose utiiity program used to create and 
maintain object module libraries for use with the linker. 

LibGen collects assembler-generated object modules into library files. From these library 
files, the object modules can be individually accessed by the linker, based on the information 
provided in each object module. 

This section describes the operations and use of LibGen, and is divided into the following 
subsections: 

• LibGen invocation. Describes how you invoke LibGen, using the TEKDOS LIBGEN 
command. 

• LibGen Execution. Describes operations performed by LibGen. 

• LibGen Output. Describes the listing file generated by LibGen. 

• LibGen Commands. Presents a detailed description of each command used to control 
the operation of LibGen. 

Some typical uses of LibGen are presented in the Operating Procedures and Programming 
Examples sections of this manual. 



LIBGEN INVOCATION 

You may invoke LibGen by either of the following methods: 

• Interactive Invocation. Allows you to control LibGen using a series of commands. 
These commands direct LibGen to examine or alter the library by inserting, deleting, or 
replacing object modules, or copying object modules to other disc files. 

Interactive invocation is the most common method of invoking LibGen. 

• Command File Invocation. Allows you to place commands normally given in interactive 
invocation into a file. You can then direct LibGen to process those commands when you 
specify only the filename. 

Command file invocation is helpful whenever a particular sequence of LibGen 
commands must be used more the once. The sequence of commands can be entered 
once to a disc file, then processed many times by LibGen. If you invoke LibGen from a 
TEKDOS command file, then command file invocation can be used. In this case, 
interactive invocation will not suffice, since it requires you to be present during 

I ibfiPn's PXPlltinrv this is npnorpllv nnt true in normal neo r\4 TCI/nnC ^^r^.r^. a r,^l f.\^^ 

These two methods of invocation are described on the following pages. 
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Interactive Invocation 



SYNTAX 

[iist-file[/disc-drive]~| 
list-device J [old-lib[/disc-drive]] 



PARAMETERS 



new-lib 
disc-drive 

list-file 
list-device 

old-lib 



The name of the output library disc file. 

A disc drive number. If you omit the disc drive number, the current 
system drive is selected. 

The name of the LibGen listing file. 

The name of the device (LPT1, CONO, etc.) that will receive the LibGen 
listing file. 

The name of the input library disc file. 



EXPLANATION 



In interactive LibGen invocation, you designate the input and output library files, and the 
listing file. LibGen will display a prompt character (an asterisk), and wait for you to enter a 
series of LibGen commands. (These LibGen commands are described individually later in this 
section.) After you have entered the LibGen END command, LibGen processes the files you 
have specified. 

LibGen can be used to create new library files, modify existing library files, or examine 
existing files. To create a new library file, omit the old-lib parameter. To modify an existing 
library file, include both the old-lib and new-lib parameters; any unmodified contents of the 
old library are copied to the new library. To examine an existing library file, omit the new-lib 
parameter. 

You may optionally specify the filenames with the NEWLIB, OLDLIB, and LIST commands, 
rather than specifying them in the LIBGEN command line. Refer to the LibGen Commands 
subsection of this section for information on these commands. 
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LIBGEN MYLIB;Y/1 LPT1 SYSLIB%Y/0 

This invocation of LibGen designates MYLIB;Y (on drive 1) as the output library file, the 
lineprinter (LPT1 ) as the device that will receive the listing, and SYSLIB%Y (on drive 0) as the 
input library file. After invocation, LibGen prompts for a sequence of commands. 

LIBGEN FPLIB;Y FPLIB;K/1 

This LibGen invocation creates a new library file, FPLIB;Y on the system drive. A listing file 
FPLIB;K (on drive 1) is also created. After this invocation, LibGen prompts for a series of 
commands. 

LIBGEN, ,LPT1 MYLIB;Y/1 

When the name of the output library file is omitted, as in this invocation, no output library file 
is created. The output library file can be omitted when you only need a listing of the contents 
of a library file, or you want to extract one or more library modules to object files. 

LIBGEN 

In this invocation of LibGen, no input, output, or listing files are specified. LibGen commands 
(such as NEWLIB, OLDLIB, and LIST) must be used to specify the appropriate input and 
output files. 
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Command File Invocation 



SYNTAX 



I@command-device-name 
@command-filename[/disc-drive] 



PARAMETERS 



command-device- 
name 



The input device (CONI, PPTR, etc.) from which LibGen will read a 
series of commands. 



command-filename 



The name of the disc file from which LibGen will read a series of 
commands. 



disc-drive 



A disc drive number. If this drive number is omitted, the current 
system drive is selected. 



EXPLANATION 



This invocation of LibGen is similar to interactive invocation. In this case, however, 
commands are read from the designated file or device, instead of from the system terminal. 
Commands are read from the specified file until the END command is read, or until the end of 
the file is reached (whichever comes first). 



EXAMPLES 



LIBGEN 0LBGNFILE/1 

This invocation line executes the LibGen commands contained in disc file LBGNFILE on drive 
1. 
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LibGen Execution 



LiBGEN EXECUTION 

LibGen performs operations on library files by copying an old library file into a new one. 
Changes, as specified by LibGen commands, are made during the copying process. This 
process is illustrated in Fig. 8-1. 
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Fig. 8-1. LibGen information flow. 



This figure illustrates the information flow into and out of the library generator (LibGen). LibGen takes 
information from the old library and designated object modules, and produces the new library, listing, 
and object files. The LibGen commands that designate the filenames used for each file are given along 
each data path line. The END, LOG and NOLOG commands are not shown, since they do not control the 
direction of information flow in LibGen. 

Any of the information paths in Fig. 8-1 can be omitted when they are not necessary. For 
example, if you are creating a new library, then no old library is needed. If you are examining 
an old library, then no new library need be created. If you do not need a listing, do not specify 
one. 

Three of the filenames may be specified in the LibGen invocation line: the old library file, the 
new library file, and the listing file. Other filenames and operations may be specified only 
with the indicated LibGen commands. 
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LibGen does not process each command at the time you enter it, but saves all commands to 
be processed in a specific order. LibGen processes commands in this order: 

1. INSERT BEFORE 

2. EXTRACT 

3. DELETE 

4. INSERT AFTER 

The REPLACE command is processed as a combination of the DELETE and INSERT AFTER 
commands. 



LIBGEN OUTPUT 

LibGen produces three different types of output files: the new library file, a listing file, and 
zero or more object files (if specified with the EXTRACT command). 



The New Library File 

The new library file is the primary product of the library generator. The new library contains 
all the object modules from the old library, plus any object modules that were inserted, minus 
any object modules that were deleted. 



The Listing 

The listing summarizes the operations that LibGen has performed. The listing consists of 
three parts: 

1. a command log; 

2. a new library symbol list; and 

3. a summary of actions performed by LibGen. 

Each of these listing parts is described in detail in the following paragraphs. 

Error messages may also be generated by LibGen as a result of mistaken information or 
requests. These error messages are described at the end of this subsection. 



Command Log 

The command iog lists each LibGen command used in the current invocation. The command 
log is optional; you can enter the LOG command to include the log in the listing, or the 
NOLOG command to omit the log. When you specify neither of these commands, the 
command log is included by default. 
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In this part of the listing, LibGen records the names of all moduies contained in the output 
library, and the global symbols contained within each module. 

Global symbols within each module are divided into three categories: 

• Section names: The name of a SECTION, COMMON, or RESERVE contained within the 
module. 

• Entry points: An address (within the most-recently-listed section) declared global with 
the assembler GLOBAL directive. 

• Global symbols: A scalar value declared global with the assembler GLOBAL directive. 

These symbols are preceded in the listing with either a (S), (E), or (G), indicating section 
name, entry point, or global symbol, respectively. 

Note that these global symbols are the factors that determine whether or not a module will 
be included at link time. For example, assume that module X in the library has a section 
named "P", an entry point named "P1 ", and a global symbol named "P9". At link time, if any 
one of the symbols "P", "P1 ", or "P9" has been referenced (through an unbound GLOBAL 
reference), and this library had been given as linker input, then module X would be included 
as if it were one of the normal linker object modules. 



Summary of Action 

The summary of action describes the operations LibGen has performed during this execution. 
LibGen actions include: 

• generating a new library, 

• deleting a module from the library, 

• inserting a module into the library, and 

• extracting a library module to an object file. 



Error Messages 

Error messages are issued wherever necessary. Two types of error messages can appear: 

1 . Non-Fatal Errors (N): LibGen cannot process the command as entered, due to syntax 
errors, or improper file/module specifications. Processing will continue, but the result 
may not be exactly what you had expected. 

2. Fatal Errors (F): LibGen has encountered a major problem that prevents further 
processing. The error message is displayed, and control returns to TEKDOS. 

All errors cause a message to be displayed on the system terminal. The error message will 
also appear in the LibGen listing file, if one is being generated. 
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In the following list, each error message is indicated as being a non-fatal error (N), or a fatal 
error (F). 

CAN NOT FIND END BLOCK FOR MODULE IN FILE filename. (F) filename is not a valid 
object file. Verify that you have specified the correct filenames in your INSERT and REPLACE 
commands. 

CAN NOT FIND END BLOCK FOR MODULE modname OF LIBRARY oldlib. (F) oldlib is 

not a valid library. 

comtype DATA STRUCTURE OVERFLOW. (F) Too many comtype (INSERT, DELETE, or 
EXTRACT) commands were specified in the current LibGen invocation. LibGen allows a 
maximum of 100 commands of any given type. 

COULD NOT FIND MODULE modname IN oldlib, newmod INSERTED AT END OF 
newlib. (N) The BEFORE/AFTER parameter of an INSERT command specified a library 
module not present in the old library. The module will be added to the end of the library. 

FILE filename IS NOT AN OBJECT FILE. (F) filename is not a valid object file. Verify that 
you have specified the correct filenames in your INSERT and REPLACE commands. 

filename I/O ERROR #nn. (F) TEKDOS has reported an I/O error during the access of the 
specified file. The error number is the service call (SVC) status byte value in hexadecimal. 
Refer to the Error Codes section of the 8002A System Users Manual for a description of the 
error and for possible actions to take to correct the situation. 

ILLEGAL COMMAND. (N) The command specified is not a valid LibGen command. Refer to 
the list of valid LibGen Commands later in this section. The command line is ignored. 

INDIRECT FILE DEPTH EXCEEDED. (N) An @filename command was read from a 
command file. Command files may not invoke other command files. The command is ignored. 

INVALID FILE NAME. (N) A filename contains an invalid character. The invalid character(s) 
are deleted, and processing continues. 

INVALID OBJECT FORMAT FOR FILE filename LOCATION = nnnn. (F) filename is not a 

valid object file. Verify that you have specifed the correct filenames in your INSERT and 
REPLACE commands. 

MODULE(S) NOT FOUND IN oldlib. (N) The modules specified in an EXTRACT or DELETE 
command were not found in the old library. The command is ignored. 

NO OLD LIBRARY GIVEN, filename INSERTED AT END OF newlib. (N) The 

BEFORE/AFTER parameter of an INSERT command specified a library module, but no old 
library was given The module will be added to the end of the new library. 
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oidiib NOT A LIBRARY. (F) oldllb is not a library file. Verify that you have specified the 
proper filename in the LibGen invocation line, or the parameter of an OLDLIB command. 

SYNTAX ERROR. (N) The command does not conform to the proper syntax for that 
command. The command line is ignored. 

UNABLE TO ASSIGN file. (N) file is not present on the disc. Verify that you have entered 
the proper filename. 

WARNING. DUPLICATE MODULE NAME: modname. (N) Two or more modules within the 
library file have the name modname. This condition does not affect the performance of the 
linker when selecting modules, but will make future modification and maintenence of the 
library difficult. When creating a library, be sure to give each object module a unique name 
with the assembler NAME directive. 



LIBGEN COMMANDS 

LibGen commands allow you to control the operations that LibGen will perform. When you 
invoke LibGen interactively, you must enter one (and only one) command each time LibGen 
prompts with an asterisk. When you invoke LibGen with a command file, each line of the 
command file should contain one LibGen command. 

Whenever you enter a series of LibGen commands, the last command must be the END 
command. If you invoke LibGen with a command file, you may omit the END command. 

In the following command descriptions, the same conventions are used as described in the 
Assembler Introduction section of this manual. Additionally, the following abbreviation 
convention is used. 

Most commands can be entered either of two ways: 

1. using the full name of the command (INSERT), or 

2. using the designated abbreviation (I). 

The designated abbreviation for each command is indicated by the underlined portion of the 
command in the syntax description. If all letters in the command are underlined, then no 
abbreviation is permitted. Partial abbreviations are never permitted. 
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Invokes a LibGen command file 



SYNTAX 



@filename[/disc-drive] 



PARAMETERS 



filename 



The name of the command file containing a sequence of LibGen 
commands. 



disc-drive 



The disc drive number on which the command file resides. If the drive 
number is omitted, the current system drive is used. 



EXPLANATION 



This command invokes filename as a command file. The command file contains a series of 
LibGen commands. Commands are read from the file and processed as if you had entered 
them from the system terminal, until the END command is read or the end of file is reached. 
Commands are echoed on the system terminal as they are processed. When the end of the 
command file is reached, you will be prompted for additional LibGen commands. Nested 
command files are not allowed: a command file may not invoke another command file. 



EXAMPLES 



§LIBIT/1 

This LibGen command invokes command file LIBIT (on drive 1). Additional LibGen commands 
will be read from file LIBIT and processed, until the end of file is reached, or until an END 
command within LIBIT is processed. 
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LibGen Command: DELETE 



Deletes library modules 



SYNTAX 



DELETE module-name [.module-name].. 



PARAMETERS 



module-name The name of an input library module that you want to delete from the 

output library. 



EXPLANATION 

The DELETE command prevents the designated modules from being copied from the old 
library file into the new library file. 

If two or more modules with the designated name exist, every module with that name is 
deleted. 



EXAMPLES 

DELETE MYMOD 
This DELETE command removes MYMOD from the output library. 

DELETE 10. OPS, FPOINT, RAND0M$$ 

This DELETE command removes modules 10. OPS, FPOINT, and RANDOM$$ from the output 
library. 



@ 
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SYNTAX 



END 



EXPLANATION 



The END command signals the end of the command sequence. You enter this command to 
start the library generation process after you have completed entering all other LibGen 
commands. 

This command must be used in interactive invocation, but it can be omitted for command file 
invocation. If END is omitted, LibGen begins the library generation process when the end of 
the command file is reached. 
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LibGen Command: EXTRACT 



Copies module to object file 



SYNTAX 
EXTRACT module-name TO filename[/disc-drive] 



PARAMETERS 



module-name The name of a library module to be copied to a disc file. 

filename The name of the file that is to receive a copy of the library object 

module. 

disc-drive The disc drive number on which filename resides. If the drive number is 

omitted, the current system drive is used. 



EXPLANATION 



The EXTRACT command copies the designated library object module to a TEKDOS disc file. 
The designated object module remains in the library (unless it has also been designated in a 
DELETE command). If the specified file already exists, it is replaced by the designated library 
object module; the old contents are lost without warning. 



EXAMPLES 



EXTRACT FP$MULT TO FPMULT;0/1 

This EXTRACT command copies the library module FPSMULT to the disc file FPMULT;0 on 
drive 1. 

EXTRACT 10. MOD TO I0;0 

This EXTRACT command copies the library module 10. MOD to the disc file I0;0 on the 
system drive. 



@ 
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SYNTAX 



INSERT filename[/disc-drive] [,filename[/disc-drive]. 



[AFTER lib-module-name 1 
BEFORE lib-module-namej 



PARAMETERS 



filename 



The name of an object file containing one of the object modules to be 
inserted. 



disc-drive 



The disc drive number on which filename resides. If the drive number is 
omitted, the current system drive is used. 



lib-module-name The name of an object module already present in the library. 



EXPLANATION 



The INSERT command adds new object modules into the library. Each specified object file 
contains one object module. These modules are placed into the new library file according to 
the BEFORE/AFTER parameter (or its absence). If more than one object module is specified, 
all designated object modules are placed together in the given order, with the entire group 
located according to the BEFORE/AFTER parameter. 



The BEFORE/AFTER parameter controls the placement of the module(s) in the following 
manner: 

• If the BEFORE/AFTER parameter is omitted, the object module(s) are placed at the 
beginning of the library. 

• If the BEFORE parameter is given, the object module(s) are placed immediately before 
the designated library module (lib-module-name). 

• If the AFTER parameter is given, the object module(s) are placed immediately AFTER 
the designated library module (lib-module-name). 

If the BEFORE/AFTER parameter is entered, but the designated library module cannot be 
found in the library, an error is generated, and the object module(s) are placed at the end of 
the library. 
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Adds new modules to library 



EXAMPLES 



INSERT I0;0 

This INSERT command adds the contents of file IO;0 (located on the system drive) to the 
beginning of the library. 

INSERT FPADD;0/1, FPSUB;0/1, FPMULT;0/1 

This INSERT command adds the contents of files FPADD;0, FPSUB;0 and FPMULT;0 (all 
located on drive 1) to the beginning of the library. 

INSERT FPDIV;O/0 BEFORE FP$MULT 

This INSERT command adds the contents of file FPDIV;0 (located on drive 0) to the library 
file. The object module contained in FPDIV;0 is placed immediately before the library object 
module named FP$MULT. 

INSERT FPCLR;0, FPR0T;0, FPSIGN;0 AFTER FP$ADD 

This INSERT command adds the contents of object files FPCLR;0, FPROT;0, and FPSIGN;0 
(all located on the system drive) immediately after the library module FP$ADD. 
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I output-device-name ) 
filename[/disc-drive] j 



SYNTAX 



PARAMETERS 



output-device-name The name of an output device (CONO, LPT1, etc.) on which the 
LibGen listing will be displayed. 



filename 
disc-drive 



The name of the LibGen listing file. 

The disc drive number on which filename resides. If the drive number 
is omitted, the current system drive is used. 



EXPLANATION 



The LIST command specifies the file or device for the LibGen listing. Refer to the LibGen 
Output subsection of this section for information on the contents of the listing. 

The listing file may also be specified by the second parameter of the LIBGEN command 
during interactive invocation. 



EXAMPLES 

LIST LPT1 
This LIST command designates the line printer (LPT1) to receive the LibGen listing. 

LIST MYLIB;N/1 

This LIST command designates disc file MYLIB;N (located on drive 1) to receive the LibGen 
listing. 
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LibGen Command: LOG 

Enables command recording 



SYNTAX 



LOG 



EXPLANATION 

1 1 1\^ i-v/\j ^<-» uiiu KougCo un 3uu3Gvjucin i_iiJvjoii v_wi 1 11 1 id i iuo iu uc iciiOiucu \iuyy6u/ III iiie 

LibGen listing file. Each command, as entered, appears in a section of the LibGen listing file 
for future reference. 

The NOLOG command disables the recording of LibGen commands in the LibGen listing file. 

The default setting is logging enabled (identical to the effect of the LOG command). 
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Specifies output library 



SYNTAX 



NEWLIB filehame[/disc-drive] 



PARAMETERS 



filename 
disc-drive 



The name of the new library file. 

The disc drive number on which filename resides. If the drive number is 
omitted, the current system drive is used. 



EXPLANATION 



The NEWLIB command designates the output disc file that is to receive the updated library. If 
the specified file currently exists, that file is replaced (without warning) with the new library 
file. If more than one NEWLIB command is entered in a command sequence, or NEWLIB 
commands are specified during an interactive invocation, only the file specified in the last 
NEWLIB command processed is used as the output library file. 

When LibGen is invoked with a command file, the NEWLIB command is essential for 
specifying the output library file. However, when LibGen is invoked interactively, the output 
library file may be specified either as the first parameter of the TEKDOS LIBGEN command, 
or as the parameter of a LibGen NEWLIB command. 



EXAMPLES 

NEWLIB FPPACKJY/1 
This NEWLIB command designates FPPACK%Y (located on drive 1) as the output library file. 
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LibGen Command: NOLOG 

Disables command recording 



SYNTAX 



NOLOG 



EXPLANATION 



The NOLOG command disables the recording (logging) of LibGen commands in the LibGen 
listing file. Refer to the LOG command for further information. 

The default setting is logging enabled (identical to the effect of the LOG command). 
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SYNTAX 



OLDLIB filename[/disc-drive] 



PARAMETERS 



filename 
disc-drive 



The name of the old library file. 

The disc drive number on which filename resides. If the disc drive 
number is omitted, the current system drive is used. 



EXPLANATION 



The OLDLIB command designates the input disc file that contains the source library. If more 
than one OLDLIB command is entered in a command sequence, or OLDLIB commands are 
specified during an interactive invocation, only the file specified in the last OLDLIB command 
processed is used as the input library file. 

When LibGen is invoked with a command file, the OLDLIB command is essential for 
specifying the input library file. However, when LibGen is invoked interactively, the input 
library file may be specified either as the third parameter after the TEKDOS LIBGEN 
command, or as the parameter of a LibGen OLDLIB command. 



EXAMPLES 

OLDLIB FPPACK5&Y/1 
This OLDLIB command designates FPPACK%Y (located on drive 1) as the input library file. 
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LibGen Command: REPLACE 

Replaces old module with new module 



SYNTAX 
REPLACE lib-module-name BY filename[/disc-drive] 



PARAMETERS 



lib-module-name The name of an object module already present in the library, 
filename 



disc-drive 



The name of a fiie containing an object module that wiii replace lib- 
module-name. 

The disc drive number on which filename resides. If the drive number is 
omitted, the current system drive is used. 



EXPLANATION 



The REPLACE command replaces the designated library module with the contents of an 
object file. The old library module is deleted (as if the appropriate DELETE command were 
entered), and the object module contained within the object file is inserted in its place (as if 
the appropriate INSERT AFTER command were entered). 

If more than one library module has the specified module name, then all modules with that 
name are deleted, and the new object module replaces the first library module with that 
name. 

If the specified file does not exist, the library module is deleted and an error occurs. 



EXAMPLES 



REPLACE FP$ADD BY NEWADD;0/1 

This REPLACE command deletes module FPSADD from the library and inserts the contents of 
object file NEWADD;0 (located on drive 1) in its place. 
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Section 9 
PROGRAMMING EXAMPLES 



INTRODUCTION 

This section contains examples of some typical uses of the assembler, linker, and library 
generator. These examples range from a simple macro invocation, to the creation and use of 
a complex floating-point library. 

These examples assume that you have some familiarity with assembly language 
programming, and with the TEKDOS Assembler, Linker, and Library Generator. You can use 
these examples as "application notes" for the assembler, linker, and library generator's 
features. These examples are not intended to be used during your initial familiarization with 
these subsystems. 

The following examples are included in this section: 

• Using a simple assembler macro. This example creates a small, general-purpose 
assembler macro, and shows some typical ways you can create, define, and invoke a 
macro. 

• Creating and using a subroutine library. This example shows how you can build a 
library (a skeleton floating-point package), and then use parts of that library at a later 
time. Relevant parts of the assembler, linker, and library generator are illustrated. 

• TEKDOS SVC generation. This example shows how the macro and conditional 
assembly features of the assembler can make it easier to use SVCs (service calls) under 
TEKDOS. 

• Creating constant values. This example shows how to use an assembler macro to 
declare a constant value in a separate assembler section. You could use this technique 
to keep your instructions, fixed data values, and variable data values separate, so that 
you could eventually place your program into ROM. 

• Save-and -restore macro. This example shows a typical application of an intelligent 
macro to perform a common programming operation: saving registers on the stack and 
later restoring the registers from the stack. 

• Conditional assembly. This example suggests ways of using the IF assembler directive 
to include or omit various program segments, based on various conditions. 

• Using the '@' construct within macros. This example shows typical uses of the '@' 
construct within macros. 

• The assembler INCLUDE directive. This example shows some typicai uses of the 
INCLUDE directive, such as providing common constant, COMMON, or macro 
declarations. It also shows how to provide a copyright or authorship notice for your listings. 
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USING A SIMPLE ASSEMBLER MACRO 

This example illustrates the use of a small, general-purpose assembler macro. The macro 
generates multiple copies of an assembler statement. 

First, the macro is defined. Then, the example shows alternative ways of defining the macro, 
using various assembler features. Finally, a few sample invocations of the macro are 
presented. 

The macro itself is simple. The macro is invoked with two parameters: an integer and an 
assembler statement. The first parameter designates how many copies to generate. For 
example, if the macro is given the two parameters of 16 and " WORD 0", the macro will 
generate 16 lines of " WORD 0". Other invocations are given later in this example. 



The COPY Macro 



C0PY$ 

'2' 

C0PY$ 


MACRO 

SET 

REPEAT 


COPY 

1 

C0PY$<=' 1 ' 


SET 

ENDR 

ENDM 


C0PY$+1 



; line 


1 


; line 


2 


; line 


3 


; line 


4 


; line 


5 


; line 


6 


; line 


7 



The macro is named COPY (in line 1), to remind you of its function: generate multiple copies 
of a designated assembler statement. Generally, you should give a macro a name that 
reflects its purpose. 

Line 2 sets the assembler variable COPY$ to 1 . This variable (COPY$) is used later in the 
body of the macro to keep track of the number of copies generated. 

Line 3 begins a REPEAT loop. The REPEAT assembler directive causes all statements 
between this directive and the matching ENDR directive (line 6) to be repeatedly assembled. 
The assembler stops assembling these statements when the condition of the REPEAT loop 
(the first operand in the REPEAT directive) is false (zero). 

For this macro, the condition expression is zero when the value of the assembler variable 
COPY$ is not less than or equal to (<=) the first parameter ('1') specified when COPY is 
invoked. In other words, the two statements within the REPEAT loop are repeatedly 
assembled as long as the assembler variable COPY$ is not greater than the first parameter. 

Line 4 is a placeholder for the second parameter specified in the macro invocation line. 
When the assembler processes this statement, it replaces the '2' with the the assembler 
statement that is to be copied. 

Line 5 increments the "number-of-copies" counter, COPY$. This counter is incremented 
once each time the statements within the REPEAT loop are assembled, to keep track of the 
number of copies generated. 
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Using a Simple Assembler Macro 



Line 6 terminates the REPEAT loop. As long as the condition of the REPEAT loop is non-zero 
(true), the assembler will return to the REPEAT statement for another pass through the 
REPEAT loop. When the condition is zero (false), the assembler proceeds with assembly 
following the ENDR statement. 

Line 7 terminates the definition of macro COPY$. 

Defining the Macro 

The macro can be defined in three different ways: 

1 . The macro can be placed at the beginning of the assembly source file that needs to 
use the macro. 

2. The macro can be placed in a separate file, and brought into the source file with an 
INCLUDE assembler directive. 

3. The macro can be placed in a separate file, and concatenated to the beginning of the 
source file when you specify the TEKDOS ASM command. 

These alternatives are described in the following paragraphs. 

Defining the Macro As Part of Source File 

If the macro is needed for only one assembler source file, this method of definition is easiest. 
Simply place the lines forming the macro definition somewhere in your source file before the 
first invocation of the macro. A typical place would be somewhere near the beginning of the 
file. 

This method is illustrated in Fig. 9-1. 





Assembly Source Program 










Macro definition 




Macro invocation 




Macro invocation 




Macro invocation 
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Fig. 9-1 . Defining a macro as part of the source file. 

In this method, the macro is defined once, near the beginning of the file. The macro may then be 
invoked as needed. 
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Defining the Macro Using the INCLUDE Directive 

If the same macro is needed in several assembler source files, you can place the macro in a 
separate file, then refer to the file name with an assembler INCLUDE directive. 

For example, you can place the lines defining the macro into a disc file named COPYMACR 
on your system disc. Then, you'd place the INCLUDE statement in your assembler source file 
(before your first invocation of the macro): 



Label Operation 
INCLUDE 



Operand Comment 

"COPYMACR" ; Obtain COPY macro definition 



When the assembler processes this statement, it will examine the contents of file 
COPYMACR, which defines the macro COPY. This method is illustrated in Fig. 9-2. 



Source program PROG;S 


Mo^m t\ in rnovMAf-B 










Definition of COPY 


INCLUDE "COPYMACR" 










Macro invocation 








Macro invocation 








Macro invocation 









3454-20 



Fig. 9-2. Defining a macro with an INCLUDE directive. 



In this method, the contents of file COPYMACR are brought into the assembler source file PROG;S, at 
the point indicated by the INCLUDE directive. This way, the macro is defined before its first invocation. 

Defining the Macro in a Concatenated Prefix File 

This definition method is much like the INCLUDE method. However, in this case, the filename 
containing the macro definition is not specified by an assembler statement, but is specified 
at the time you enter the ASM command. 

Let's assume again that the macro resides in a file named COPYMACR, and that your source 
program is named PROG;S. To assemble your source program, you enter the following 
TEKDOS command line: 

> ASM PR0G;0 PR0G;L COPYMACR PR0G;S 

v V ^ 

Prefix file 



»-*+ 
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Using a Simple Assembler Macro 



Notice what happens: the file COPYMACR is effectively "glued" to the front of the source 
program PROG;S by this TEKDOS ASM command line. The assembler will read and process 
the contents of COPYMACR before processing the statements of PROG;S, thus ensuring that 
the COPY macro will be defined before its first use. This process is illustrated in Fig. 9-3. 



Macro file (COPYMACR) 



Source program (PROG;S) 



Definition of COPY 



Macro invocation 



Macro invocation 



Macro invocation 



3454-21 



Fig. 9-3. Defining a macro in a concatenated prefix file. 

In this method, the macro definition file (COPYMACR) is attached by the assembler to the beginning of 
the main program (PROG;S). 

This method has two major advantages: 

1. You specify the name of the macro definition file when you assemble the file, instead 
of when you edit the file. Sometimes you may not know the name or disc drive number 
of the definition file when you're entering the program. This method allows you to 
change the name or disc drive number without editing the file. 

2. Your macros are guaranteed to have been defined before their first use; the assembler 
processes the prefix file before it assembles any statements in the main part of the 
program. 

This method has two disadvantages that you should be aware of: 

1. The name of the macro definition file must be specified each time you assemble the 
file. This disadvantage can be minimized if you create a TEKDOS command file 
containing the assembler invocation line. 

2. The line numbers in the assembler listing are incremented for any assembled line; 
therefore, the line number of an error in the listing will not necessarily compare 
correctly with the line number of the main program source statements. In our 
example, an error appearing on line 50 of the assembler listing would actually refer to 
line 43 (in our example) of PROG;S, because the first seven lines of the listing have 
been obtained from the file COPYMACR. 



(a) 
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Sample Invocations of the COPY Macro 

Now that COPY has been defined (by one of the three methods mentioned above), you may 
use the macro in your program. For example, suppose that you need 20 (decimal) consecutive 
constant-value bytes — each byte containing the value 47 (decimal). Without the aid of this 
macro, you would need to enter the BYTE directive with 20 operands (each being the value 
47), or 20 BYTE directives, each with an operand of 47, or some combination of the above 
entries. With the aid of the macro, however, you only need to write one assembler statement: 

COPY 20, [ BYTE 47] 

Notice that the second parameter is enclosed in matching square brackets. These brackets 
are not part of the parameter, but indicate the part of the statement line that belongs to the 
parameter. Without the brackets, the essential leading space (before the word BYTE) would 
have been discarded, and the assembler statements (generated within the macro) would 
have been in error. 

Another example of a need for multiple copies of an assembler statement can be taken from 
the microprocessor instruction set. An 8080A/8085A RLC instruction rotates the 
accumulator (A register) one bit-position to the left. You may need to rotate the accumulator 
four bit-positions to the left; the 8080A/8085A does not provide this as a primitive 
instruction. Ordinarily, you would have to generate four consecutive RLC instructions; with 
the COPY macro, you can enter these four statements with one line: 

COPY 4,[ RLC] 

Again, the brackets surround the second parameter to retain the required leading space. 



CREATING AND USING A SUBROUTINE LIBRARY 

This example shows you how to create a library using the assembler and library generator, 
and how to write programs that use selected modules from the library. 

The example develops a portion of a floating-point package. The floating-point package uses 
processor instructions to manipulate floating-point numbers like 10000. or it (3.14159...). For 
this example, assume that any floating-point number can be stored in eight consecutive 
bytes. (The method of storage is not relevant to this example.) 

To keep things simple, only two primitive floating-point operations are shown in this 
example: addition and subtraction. Modules that perform these two operations are the 
nucleus of the library. Later, other modules, such as multiplication, could be added to the 
library. 

In this example, the addition and subtraction modules are written as subroutines. They pass 
and return data using a predefined COMMON section: a floating-point accumulator. (See the 
Add Module and Subtract Module discussions.) 



a. a 
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Creating and Using a Subroutine Library 



This example, then, consists of seven major tasks: 

1. The library ADD module is presented. 

2. The library SUUBTRACT module is presented. 

3. The modules are entered and assembled. 

4. The library generator is invoked to create the floating-point library from the two object 
modules. 

5. A sample mainline program using the library ADD module is presented. 

6. The sample mainline program is entered, assembled, and linked. 

7. A parallel mainline program using the library SUBTRACT module is presented, 
entered, assembled, and linked. 



The Add Module 

The following assembler source statements present a "skeleton" of the library ADD module. 
The actual microprocessor instructions to perform the addition are not included, but are 
represented by assembler BLOCK directives of comparable length. A line-by-line description 
of the source module follows the listing. 



The ADD Module Statements 





LIST 


DBG 




NAME 


FP$ADD 




GLOBAL 


FP.ADD, FP.AD2 




COMMON 


FP$ACC 


SRC1 


BLOCK 


8 


SRC2 


BLOCK 


8 


DEST 


BLOCK 


8 




SECTION 


FP ADD 


FP.ADD 


BLOCK 


40 


FP.AD2 


BLOCK 
END 


350 



line 


1 


line 


2 


line 


3 


line 


4 


line 


5 


line 


6 


line 


7 


line 


8 


line 


9 


line 


10 


line 


11 



Explanation of the ADD Module 

Line 1 enables the linker to generate a listing of all internal (non-global) symbols with their 
relocated values. Although you wouldn't normally enable this feature in a library module, you 
can use it here to observe the normally invisible linker operations. 

Line 2 declares the name of the object module generated by the assembler from these source 
statements. This name is essential in all LibGen references to this particular library element. 
The name (FP$ADD) indicates the module's function (floating-point addition). 

Line 3 designates FP.ADD and FP.AD2 as global symbols. Both of these symbols are defined 
in this module. These symbols are entry points into the subroutine; they are used by other 
modules to select this library module at link time. 
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Lines 4 through 7 define the structure of the floating-point accumulator. This COMMON 
section is named FP$ACC (floating-point accumulator). The accumulator provides space for 
three floating-point numbers: two operands (SRC1 and SRC2) and the result (DEST). 

Lines 8 through 1 define the executable-instruction section named FP_ ADD. This assembler 
section contains the instructions that perform the addition. The BLOCK directives represent the 
approximate number of bytes consumed by the instructions. Two entry points are defined in this 
section: FP.ADD and FP.AD2. (See the following discussion.) 

Line 11 designates the end of this assembler module. 



Entry Points 

This library module defines two entry points: 

• Your program can call this subroutine at FP.ADD to add SCR 1 to DEST, leaving the result in 
DEST. This entry point is useful when you are maintaining a running total. To simplify the 
discussion, assume that the routine beginning at FP.ADD simply copies the contents of 
DEST to SCR2, then falls through to the routine at FP.AD2. 

• Your program can call this subroutine at FP.AD2 to add SRC1 to SRC2, leaving the 
result in DEST. This entry point is used when you do not wish to incur the additional 
overhead of the first entry point. 



The Subtract Module 

The SUBTRACT module, as represented here, is very similar to the ADD module. The 
assembler statements present a "skeleton" of this SUBTRACT module. A line-by-line 
description of the source module follows the listing. 



The SUBTRACT Module Statements 





LIST 


DBG 




NAME 


FP$SUB 




GLOBAL 


FP.SUB, FP.SU2 




GLOBAL 


FP.AD2 




COMMON 


FP$ACC 


S0RC1 


BLOCK 


8 


S0RC2 


BLOCK 


8 


DST 


BLOCK 


8 




SECTION 


FP SUB 


FP.SUB 


BLOCK 


1 u 


FP.SU2 


BLOCK 


30 




CALL 


FP.AD2 




BLOCK 


35 




END 





line 
line 
line 
line 
line 
line 
line 
line 
line 
line 
line 
line 
line 
line 



1 
2 
3 
4 
5 
6 
7 
8 
9 

1 r\ 

I u 

11 

12 

13 
14 
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Explanation of the SUBTRACT Module 

Line 1 enables the linker to generate a listing of all internal (non-global) symbols with their 
relocated values. 

Line 2 declares the name of the object module generated by the assembler from these source 
statements: FP$SUB (floating-point subtraction). 

Line 3 designates FP.SUB and FP.SU2 as global symbols. These address symbols form entry 
points mto this routine. 

Line 4 declares FP.AD2 as a global symbol. Unlike the other global symbols, FP.AD2 is 
defined in another module (the ADD module). When the SUBTRACT module is linked into a 
program, the linker notes the FP.AD2 symbol, and attempts to locate a definition for it in 
another module. 

Lines 5 through 8 define the structure of the floating-point accumulator. The COMMON 
section is named FP$ACC, as before. However, the components of FP$ACC are named 
differently in this module: the operands are named SORC1 and SORC2, while the destination 
is named DST. This module illustrates how two modules can refer to the same portions of 
memory with independently selected names. 

Lines 9 through 13 define the executable-instruction section named FPSUB. This assembler 
section contains the instructions that perform the subtraction. Two entry points are defined 
here: FP.SUB and FP.SU2. (See the following discussion.) 

Line 14 designates the end of this assembler routine. 



Entry Points 

This library module defines two entry points: 

• Your program can call this subroutine at FP.SUB to subtract SORC1 from DST, leaving 
the result in DST. 

• Your program can call the subroutine at FP.SU2 to subtract SORC1 from SORC2, 
leaving the result in DST. 

The routine starting at FP.SUB copies the contents of DST to SORC2, then falls through to 
FP.SU2. The routine beginning at FP.SU2 changes the sign of SORC1, and calls FP.AD2 to 
complete the subtraction. (The 8080A/8085A instruction at line 12 is a call to a subroutine, 
and returns to the address following the instruction.) 
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Entering the Modules 

You may use the TEKDOS Editor to enter these two modules into their respective assembler 
source files. The ADD module will be placed in a file named FPADD;S, and the SUBTRACT 
module will be placed in a file named FPSUB;S. The underlined entries indicate what you 
enter. 

NOTE 

These demonstrations were generated using TEKDOS Editor Version 2. If you 
have TEKDOS Editor Version 3 or above, you must enter the command 
XTABS ON immediately after each editor invocation. 

[Create the addition source file with the TEKDOS Editor.] 
> EDIT FPADD;S 

** EDIT VER 2.x ** 

**NEW FILE** 

[Define a visible tab character, and enter the assembly statements.] 

* TAB \:INPUT 

INPUT: 

\LIST\DBG 

\name\fp$add 

\global\fp.add, fp.ad2 

\common\fp$acc 

src 1\ bloc k\f 

src2\block\8 

dest\bl0ck\8 

\section\fp add 

Fp.AdD\blOck\4o 

fp.ad2\block\350 

YEND 

[Display the statements with the tab characters expanded to spaces.] 
* TYPE B-E 

LIST DBG 

NAME FP$ADD 

GLOBAL FP.ADD, FP.AD2 

COMMON FP$ACC 

SRC1 BLOCK 8 

SRC2 BLOCK 8 

DEST BLOCK 8 

SECTION FP_ADD 

FP.ADD BLOCK 40 

FP.AD2 BLOCK 350 

END 
* FILE 
*D0S* EOJ 
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[Now follow the same procedure for the subtraction source file.] 
> EDIT FPSUB;S 

" " t_l/J_ J. V J_.ll __ • A " 

**NEW FILE** 

* TAB \; INPUT 

INPUT: 

\LIST\DBG 

\NAME\FP$SUB 

\GLOBAL\FP.SUB, FP.SU2 

\UijUDiiij \r r . hue 

\COMMON\FP$ACC 

S0RC1\BL0CK\8 

S0RC2\BL0CK\8 

DST\BL0CK\8" 

\SECTI ON\FP SUB 

FP,SUB\BL0CK\70 

FP.SU2\BLOCK\30 

\CALL\FP.TD2 

\BLOCK\35 

\END 



*TYPE 


B-E 






LIST 


DBG 




NAME 


FP$SUB 




GLOBAL 


FP.SUB, FP.SU2 




GLOBAL 


FP.AD2 




COMMON 


FP$ACC 


S0RC1 


BLOCK 


8 


S0RC2 


BLOCK 


8 


DST 


BLOCK 


8 




SECTION 


FP SUB 


FP.SUB 


BLOCK 


70 


FP.SU2 


BLOCK 


30 




CALL 


FP.AD2 




BLOCK 


35 




END 




*FILE 






*DOS* 


EOJ 
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Assembling the Modules 

Now that you've entered the programs, you may assemble them to generate the necessary 
object modules for the library. 

[Assemble the source FPADD;S into the object FPADDjO. The listing is output 

to CONO (the system terminal), so that you may examine it.] 
> ASM FPADD;0 CONO FPADD;S 

Tektronix 8080/8085 ASM Vx.x 
**** Pass 2 



Tektronix 8080/8085 ASM Vx.x 



Page 



00001 








LIST 


DBG 


00002 








NAME 


FP$ADD 


00003 








GLOBAL 


FP.ADD, 


00004 








COMMON 


FP$ACC 


00005 


0000 


0008 


SRC1 


BLOCK 


8 


00006 


0008 


0008 


SRC2 


BLOCK 


8 


00007 


0010 


0008 


DEST 


BLOCK 


8 


00008 








SECTION 


FP ADD 


00009 


0000 


0028 


FP.ADD 


BLOCK 


40 


00010 


0028 


015E 


FP.AD2 


BLOCK 


350 


00011 








END 





FP.AD2 



Tektronix 8080/8085 ASM Vx.x Symbol Table 



Page 



Scalars 

A 0007 

D 0002 

L 0005 

SP 0006 

FP$ACC Common (0018) 
DEST 0010 

FP_ADD Section (0186) 
FP.AD2 - 0028 G 



B 0000 

E 0003 

M 0006 



SRC1 0000 



FP.ADD - 0000 G 



C -- 
H - 
PSW 



0001 
0004 
0006 



SRC2 --- 0008 



11 Source Lines 
1 1 Source Lines 



11 Assembled Lines 
11 Assembled Lines 



47672 Bytes available 
47672 Bytes available 



*ASM* EOJ 



>>> No assembly errors detected <<< 
>>> No assembly errors detected <<< 



[Now do the same for the subtract module: assemble FPSUB;S into FPSUB;0.] 
> ASM FPSUB;0 CONO FPSUB;S 
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Creating and Using a Subroutine Library 



Tektronix 8080/8085 ASM Vx.x 
**** p ass 2 



1CM/I UII1A 


cnan /flnfic; 


A SM V x .'. 


V 




00001 








LIST 


DBG 


00002 








NAME 


FP$SUB 


00003 








GLOBAL 


FP.SUB, FP.SU2 


00004 








GLOBAL 


FP.AD2 


00005 








COMMON 


FP$ACC 


00006 


nnnn 

\J W U V 


nnnQ 


cnop 1 


di nrv 


a 


00007 


0008 


0008 


S0RC2 


BLOCK 


8 


00008 


0010 


0008 


DST 


BLOCK 


8 


00009 








SECTION 


FP SUB 


00010 


0000 


0046 


FP.SUB 


BLOCK 


70 


00011 


0046 


001E 


FP.SU2 


BLOCK 


30 


00012 


0064 


CD0000 > 




CALL 


FP.AD2 


00013 


0067 


0023 




BLOCK 


35 


00014 








END 




Tektronix 


8080/8085 


ASM Vx.: 


x Symbo 


1 Table 


Scalars 











Paee 



A 0007 

D 0002 

L 0005 

SP 0006 

FP$ACC Common (0018) 

DST 0010 

FP_SUB Section (008A) 

FP.SU2 - 0046 G 
FP.AD2 Unbound Global 



B 0000 

E 0003 

M 0006 



S0RC1 -- 0000 



FP.SUB - 0000 G 



C 

H 

PSW -■ 



Page 



0001 
0004 
0006 



S0RC2 -- 0008 



14 Source Lines 
14 Source Lines 



14 Assembled Lines 
14 Assembled Lines 



47656 Bytes available 
47656 Bytes available 



*ASM* EOJ 



>>> No assembly errors detected <<< 
>>> No assembly errors detected <<< 



& 
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Creating the Library 

Now, you can use the library generator (LibGen) to create the floating-point library. LibGen is 
discussed in the Library Generator section of this manual. Enter the underlined characters to 
create the floating-point library FP%Y from the two object modules. 

[Invoke LibGen in interactive mode.] 

> LIBGEN 

[Select the listing file name.] 
* LIST FP;N 

[Designate the name of the library.] 
* NEWLIB FP%Y 

[Now enter the list of object files to be included in this library.] 
* INSERT FPSUB;0 
* INSERT FPADD;0 

[All finished... terminate with the END command.] 
* END 

NEW LIBRARY GENERATED: FP%Y 

MODULE: FP$SUB FROM FPSUB;0 INSERTED 
MODULE: FP$ADD FROM FPADD;0 INSERTED 
*LIBGEN* EOJ 

[Display the listing on the system terminal.] 

> COPY FP;N 

Tektronix Library Generator Vx.x COMMAND LOG Page 1 

LIST FP;N 
NEWLIB FP%Y 
INSERT FPSUBjO 
INSERT FPADD;0 
END 

Tektronix Library Generator Vx.x SYMBOLS DEFINED Page 2 



MODULE: FP$SUB 

(S) FP$ACC (S) FP SUB (E) FP.SUB (E) FP.SU2 



MODULE: FP$ADD 

(S) FP$ACC (S) FP_ADD (E) FP.ADD (E) FP.AD2 

Tektronix Library Generator Vx.x SUMMARY OF ACTION Page 

NEW LIBRARY GENERATED: FP%Y 

MODULE: FP$SUB FROM FPSUB;0 INSERTED 
MODULE: FP$ADD FROM FPADDjO INSERTED 
*COPY* EOJ 
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Notice that the subtraction routine is placed before the addition routine in the library. The 
sample mainline programs (presented later) show why the modules are inserted in this order. 



UsinQ th6 ADD Moduls from s Procjram 

The information stored in the library can be used by a mainline program that references one 
of the library module's giobal entry points. The following mainline program uses the FP$ADD 
module of the library; a line-by-line annotation follows the listing. 



The Mainline Add Program 





LIST 


DBG 




NAME 


MAIN. ADD 




GLOBAL 


FP.ADD 




COMMON 


FP$ACC 


S1 


BLOCK 


8 


S2 


BLOCK 


8 


DESTN 


BLOCK 


8 




SECTION 


MAIN 


ENTRY 


BLOCK 


40 




CALL 


FP.ADD 


MORE 


BLOCK 


50 




END 


ENTRY 



line 


1 


line 


z 


line 


3 


line 


4 


line 


5 


line 


6 


line 


7 


line 


8 


line 


9 


line 


10 


line 


11 


line 


12 



Explanation of the Mainline Add Program 

Line 1 enables the linker to display all internal (non-global) symbols with their relocated 
values. This feature of the linker enables you to examine normally invisible operations. 

Line 2 gives the name MAIN.ADD to the object module. 

Line 3 declares the symbol FP.ADD as a global symbol. This symbol is not defined in this 
object module; therefore, the symbol is called an "unbound" global. The linker will attempt to 
locate a definition for FP.ADD; the library FP%Y (created earlier) will provide this definition. 

Lines 4 through 7 define the structure of the floating-point accumulator. In this module, the 
two source fields and destination field are called S1, S2, and DESTN. 

Line 8 begins the definition of the main section (called MAIN). All object bytes generated 
after this directive are gathered into the MAIN section. 

Line 9 sets aside memory space for an unspecified number of processor instructions; these 
instructions load values into S1 and DESTN for processing. In a real program, this BLOCK 
directive would be replaced with microprocessor instructions, such as data transfer 
instructions or I/O operations. 



@ 
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Line 10 is an 8080A/8085A instruction. The subroutine FP.ADD (contained in the floating- 
point library) is invoked. The contents of S1 are added to the contents of DESTN, and the 
subroutine returns to the memory location following the CALL instruction. 

Line 11 represents more microprocessor instructions following the invocation of the ADD 
routine. These instructions might perform some type of output to display the results of the 
addition. 

Line 12 defines the end of this source module. The operand ENTRY is designated as the 
starting address of the instructions. The value of this address will be passed along to the 
linker; the linker then determines its relocated address, and displays this final value as a 
transfer address. 



Entering, Assembling, and Linking the Program 

The mainline add program can be entered, assembled, and linked using the following 
command entries: 

[Invoke the editor to enter the program into file MNADD;S.] 
> EDIT MNADD;S 

** EDIT VER 2.x ** 
**NEW FILE** 

[Select a visible tab character and enter the assembly statements.] 

* TAB \:INPUT 

INPUT: 

\LIST\DBG 

\NAME\MAIN.ADD 

\GLOBAL\FP.ADD 

\C0MM0N\FP$ACC 

S1\BL0CK\g 

S2\BLOCK\8~ 

DESTN\BL0CK\8 

\SECTION\MAIN 

ENTRY\BLOCK\M0 

\CALL\FP.ADD 

MORE\BLOCK\50 

\END\ENTR"Y 

[Display the lines with tab characters expanded to spaces.] 
*TYPE B-E 





LIST 


DBG 




NAME 


MAIN. A 




GLOBAL 


FP.ADD 




COMMON 


FP$ACC 


SI 


BLOCK 


8 


S2 


BLOCK 


8 


DESTN 


BLOCK 


8 




SECTION 


MAIN 


ENTRY 


BLOCK 


MO 




CALL 


FP.ADD 


MORE 


BLOCK 


50 




END 


ENTRY 


*FILE 






*D0S* 


EOJ 





V- ID 
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LIST 


DBG 




NAME 


MAIN. ADD 




GLOBAL 


FP.ADD 




COMMON 


FP$ACC 


S1 


BLOCK 


8 


S2 


BLOCK 


8 


DESTN 


BLOCK 


8 




SECTION 


MAIN 


ENTRY 


BLOCK 


40 




CALL 


FP.ADD 


MORE 


BLOCK 


50 




END 


ENTRY 



[Assemble MNADD;S into MNADD;0.] 
> ASM MNADD;0 CONO MNADD;S 

Tektronix 8080/8085 ASM Vx.x 
**** Pass 2 

Tektronix 8080/8085 ASM Vx.x Page 

00001 
00002 
00003 
00004 

00005 0000 0008 

00006 0008 0008 

00007 0010 0008 
00008 

00009 0000 0028 

00010 0028 CD0000 

00011 002B 0032 

00012 0000 

Tektronix 8080/8085 ASM Vx.x Symbol Table Page 



Scalars 

A 0007 B 0000 C 0001 

D 0002 E 0003 H 0004 

L 0005 M 0006 PSW 0006 

SP 0006 

FP$ACC Common (0018) 

DESTN — 0010 S1 0000 S2 0008 

MAIN Section (005D) 

ENTRY -- 0000 MORE 002B 

FP.ADD Unbound Global 



12 Source Lines 12 Assembled Lines 47669 Bytes available 

12 Source Lines 12 Assembled Lines 47669 Bytes available 

>>> No assembly errors detected <<< 

>>> No assembly errors detected <<< 
*ASM* EOJ 



[Link the mainline program together with the floating-point library.] 
> LINK MNADD;L MNADD;K MNADD;0 LIB(FP%Y) 

NO ERRORS NO UNDEFINED SYMBOLS 
2 MODULES 3 SECTIONS 
TRANSFER ADDRESS IS 019E 
*LINK* EOJ 
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[Display the linker listing file on the system terminal.] 
> COPY MNADD;K 

Tektronix 8080/8085 LINKER V x.x GLOBAL SYMBOL LIST Page 1 

FP$ACC 0000 FP.AD2 0040 FP.ADD 0018 FP_ADD 0018 
MAIN 019E 

Tektronix 8080/8085 LINKER V x.x INTERNAL SYMBOL LIST Page 2 



FILE: MNADD;0 

MODULE: MAIN. ADD 

SCALARS: 

A 0007 B 0000 C 0001 D 0002 

E 0003 H 0004 L 0005 M 0006 

PSW 0006 SP 0006 

LABELS: (SECTION FP$ACC ) 

DESTN 0010 S1 0000 S2 0008 

LABELS: (SECTION MAIN ) 

ENTRY 019E MORE 01C9 

Tektronix 8080/8085 LINKER V x.x INTERNAL SYMBOL LIST Page 3 



FILE: FP5&Y 

MODULE: FP$ADD 

SCALARS: 

A 0007 B 0000 C 0001 D 0002 

E 0003 H 0004 L 0005 M 0006 

PSW 0006 SP 0006 

LABELS: (SECTION FP$ACC ) 

DEST 0010 SRC1 0000 SRC2 0008 

LABELS: (SECTION FP_ADD ) 

FP.AD2 0040 FP.ADD 0018 



Programming Examples — 8002A: Assembler Users Manual Creating and Using a Subroutine Library 



Tektronix 8080/8085 LINKER V x.x MODULE MAP Page 



rut: nnauu;u 

MODULE: MAIN. ADD 

FP$ACC COMMON BYTE 0000-0017 
MAIN SECTION BYTE 019E-01FA 



fiLt: rrii 

MODULE: FP$ADD 

FP$ACC COMMON BYTE 0000-0017 

FP_ADD SECTION BYTE 0018-01 9D 

FP.AD2 0040 FP.ADD 0018 



Tektronix 8080/8085 LINKER V x.x MEMORY MAP Page 



0000-0017 FP$ACC COMMON BYTE 

001 8-01 9D FP_ADD SECTION BYTE 

019E-01FA MAIN SECTION BYTE 

NO ERRORS NO UNDEFINED SYMBOLS 

2 MODULES 3 SECTIONS 

TRANSFER ADDRESS IS 01 9E 
*C0PY* EOJ 



Linking Explanation 

The library module containing the floating-point addition routine is automatically linked in 
with the mainline program. The linker determined that a global symbol (FP.ADD) had not 
been given a value by any of the non-library modules. The linker then scanned the library, 
and found that module FP$ADD provided a value for this global symbol. The linker included 
module FP$ADD in the load module. This process is illustrated in Fig. 9-4. 



(n) 
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Floating -point Library (FP%Y) 



MIMADD;0 

(mainline add program) 



FP$SUB 


"1 have FP.SUB" 
"1 have FP.SU2" 
"1 need FP.AD2" 



FP$ADD 



r 



I have FP.ADD" 
'I have FP.AD2" 



"I need FP.ADD" 






The linked program (MNADD;L) 



V 



(from MNADD.O) 



V 



(from FP$ADD) 



3454-22 



Fig. 9-4. Linking the add program to the library. 

In this example, MNADD;0 needs a definition for its unbound global symbol, FP.ADD. The linker 
examines the contents of the library FP%Y, and locates module FP$ADD, which provides a definition for 
FP.ADD. Both MNADD;0 and module FP$ADD are then included in the final load file. FP$SUB does not 
provide definitions for any unbound globals, so it is not included in the final load file. 



Using the SUBTRACT Module From a Program 

Let's modify the mainline program to invoke the subtract routine. In this way, we can watch 
the linker extract one module from the library to satisfy the request made by the mainline 
program, and another module from the library to satisfy the first library module. 
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Creating and Using a Subroutine Library 



The Mainline Subtract Program 





LIST 


DBG 




NAME 


MAIN. SUB 




GLOBAL 


FP.SUB 




COMMON 


FP$ACC 


S1 


BLOCK 


8 


S2 


BLOCK 


8 


DESTN 


BLOCK 


8 




SECTION 


MAIN 


ENTRY 


BLOCK 


45 




CALL 


FP.SUB 


MORE 


BLOCK 


35 




END 


ENTRY 



line 1 



line 


2 


line 


3 


line 


4 


line 


5 


line 


6 


line 


7 


line 


8 


line 


9 


line 


10 


line 


11 


line 


12 



Explanation of the Mainline Subtract Program 

The mainline subtract program is similar to the mainline add program, with the following 
exceptions: 

1. The name of the module (in line 2) is MAIN. SUB, not MAIN.ADD. 

2. The global symbol requested in lines 3 and 10 is FP.SUB, not FP.ADD. 

3. The size of the code representations in lines 9 and 1 1 has been altered, to show the 
repeatability of the library sections. 



Entering, Assembling,and Linking the Program 

Like the mainline add program, the mainline subtract program can be entered, assembled, 
and linked using the following command entries: 

[Invoke the editor to create MNSUB;S.] 
> EDIT MNSUB;S 

** EDIT VER 2.x ** 
**NEW FILE** 

[Select a visible tab character, and enter the assembly statements.] 

* TAB \:INPUT 

INPUT: 

\LIST\DBG 

\NAME\ MAIN. SUB 

\GL0BAL\FP.SUB 

\C0MM0N\FP$ACC 

S1\BL0CK\8 

S2\BL0CK\5 

DESTN\BL0CK\8 

\SECTI0N\MAIN 

ENTRY\BL0CK\45 

\CALL\FP.STJB 

MORE\BLOCK\35 

\END\ENTRY 



@ 



9-21 



Creating and Using a Subroutine Library Programminn Examples— 8002A: Assembler Users Manual 



[Displ 


.ay the expanded statements.] 


*TYPE 


B-E 






LIST 


DBG 




NAME 


MAIN. SUB 




GLOBAL 


FP.SUB 




COMMON 


FP$ACC 


S1 


BLOCK 


8 


S2 


BLOCK 


8 


DESTN 


BLOCK 


8 




SECTION 


MAIN 


ENTRY 


BLOCK 


45 




CALL 


FP.SUB 


MORE 


BLOCK 


35 




END 


ENTRY 


*FILE 






*DOS* 


EOJ 





[Assemble the source file into an object file.] 
> ASM MNSUB;Q CONO MNSUB;S 

Tektronix 8080/8085 ASM Vx.x 
**** Pass 2 

Tektronix 8080/8085 ASM Vx.x Page 



00001 








LIST 


DBG 


00002 








NAME 


MAIN. SUB 


00003 








GLOBAL 


FP.SUB 


00004 








COMMON 


FP$ACC 


00005 


0000 


0008 


SI 


BLOCK 


8 


00006 


0008 


0008 


S2 


BLOCK 


8 


00007 


0010 


0008 


DESTN 


BLOCK 


8 


00008 








SECTION 


MAIN 


00009 


0000 


002D 


ENTRY 


BLOCK 


45 


00010 


002D 


CD0000 


> 


CALL 


FP.SUB 


00011 


0030 


0023 


MORE 


BLOCK 


35 


00012 




0000 


> 


END 


ENTRY 
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Creating and Using a Subroutine Library 



Tektronix 8080/8085 ASM Vx.x Symbol Table 
Scalars 



A 0007 

D 0002 

L 0005 

SP 0006 

FP$ACC Common (0018) 
DESTN — 0010 

MAIN Section (0053) 
ENTRY -- 0000 

FP.SUB Unbound Global 



B 0000 

E 0003 

M 0006 



S1 0000 



MORE — 0030 



Page 



C 0001 

H 0004 

PSW 0006 



S2 



0008 



12 Source Lines 
12 Source Lines 



12 Assembled Lines 47669 Bytes available 
12 Assembled Lines 47669 Bytes available 



*ASM* EOJ 



>>> No assembly errors detected <<< 
>>> No assembly errors detected <<< 



[Link the mainline program with the library.] 
> LINK MNSUB;L MNSUB;K MNSUB;0 LIB(FP%Y) 

NO ERRORS NO UNDEFINED SYMBOLS 

3 MODULES 4 SECTIONS 

TRANSFER ADDRESS IS 0228 
*LINK* EOJ 



[Display the resulting linker listing file.] 
> COPY MNSUB;K 



Tektronix 8080/8085 LINKER V x.x 



GLOBAL SYMBOL LIST 



Page 



FP$ACC 0000 FP.AD2 0040 FP.ADD 0018 FP.SU2 01E4 
FP.SUB 019E FP ADD 0018 FP SUB 019E MAIN 0228 
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Tektronix 8080/8085 LINKER V x.x 



INTERNAL SYMBOL LIST Page 



FILE: MNSUB;0 
MODULE: MAIN. SUB 



SCALARS: 
















A 


0007 


B 


0000 


C 


0001 


D 


0002 


E 


0003 


H 


0004 


L 


0005 


M 


0006 


PSW 


0006 


SP 


0006 











LABELS: (SECTION FP$ACC ) 

DESTN 0010 S1 0000 

LABELS: (SECTION MAIN ) 

ENTRY 0228 MORE 0258 



S2 



0008 



Tektronix 8080/8085 LINKER V x.x 



INTERNAL SYMBOL LIST Page 



FILE: FP5&Y 
MODULE: FP$SUB 



SCALARS: 
A 
E 
PSW 


0007 
0003 
0006 


B 
H 
SP 




0000 
0004 
0006 


C 
L 


0001 
0005 


D 

M 


0002 
0006 


LABELS: 
DST 


(SECTION 
0010 


FP$ACC 
SORC1 


) 


0000 


SORC2 


0008 






LABELS: 
FP.SU2 


(SECTION 
01E4 


FP SUB 
FP.SUB 


) 


019E 











Tektronix 8080/8085 LINKER V x.x 



INTERNAL SYMBOL LIST Page 



FILE: FPU 
MODULE: FP$ADD 



CALARS: 
A 
E 
PSW 


0007 
0003 
0006 


B 
H 
SP 


0000 
0004 
0006 


C 
L 


LABELS: 
DEST 


(SECTION 
0010 


FP$ACC 
SRC1 


) 

0000 


S 


LABELS: 
FP.AD2 


(SECTION 
0040 


FP ADD 
FP.ADD 


) 

0018 





SRC2 



0001 D 
0005 M 



0008 



0002 
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Creating and Using a Subroutine Library 



Tektronix 8080/8085 LINKER V x.x 



MODULE MAP 



Page 



FILE: MNSUB'O 

MODULE: MAIN. SUB 

FP$ACC COMMON BYTE 0000-0017 

MAIN SECTION BYTE 0228-027A 



MODULE: FP$SUB 

FP$ACC COMMON BYTE 0000-0017 

FP_SUB SECTION BYTE 019E-0227 

FP.SU2 01E4 FP.SUB 019E 

MODULE: FP$ADD 

FP$ACC COMMON BYTE 0000-0017 

FP_ADD SECTION BYTE 0018-019D 

FP.AD2 0040 FP.ADD 0018 



Tektronix 8080/8085 LINKER V x.x 



MEMORY MAP 



Page 



0000-0017 FP$ACC 

0018-019D FP_ADD 

019E-0227 FP_SUB 

0228-027A MAIN 



COMMON BYTE 
SECTION BYTE 
SECTION BYTE 
SECTION BYTE 



NO ERRORS NO UNDEFINED SYMBOLS 

3 MODULES 4 SECTIONS 

TRANSFER ADDRESS IS 0228 
*COPY* EOJ 



Linking Explanation 

For the mainline subtract program, the library module FP$SUB is referenced using the global 
symbol FP.SUB. This brings module FP$SUB into the final load module. However, FP$SUB 
itself contains a reference to an unbound global symbol, FP.AD2. The definition for this 
unbound global symbol is found in the FP$ADD library module. The linker must include both 
modules from the library to satisfy all requests for global symbols. This process is illustrated 
in Fig. 9-5. 



(5) 
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Floating-point Library (FP%Y) 



FPSSUB 



MNSUB;0 

(mainline subtract program) 



'I have FP.SUB" 
'I have FP.SU2" 
'I need FP.AD2" 



FP$ADD 



'I have FP.ADD' 
'I have FP.AD2" 



"I need FP.SUB" 



_U 



xz 



(from MNSUB;0) 



V 



(from FP$SUB) 



V 



(from FP$ADD) 



The linked program (MNSUB;L) 



3454-23 



Fig. 9-5. Linking the subtract program to the library. 



In this linking example, MNSUB;0 requests definition for an unbound global, FP.SUB. The linker scans 
the library (starting at the left in this figure), and locates a definition for FP.SUB, in module FP$SUB. 
However, FP$SUB itself contains a reference to an unbound global symbol, FP.AD2. The linker 
continues to scan the library, and finds a definition for FP.AD2 in library module FP$ADD. Thus, the 
final load file contains all three modules (mainline MNSUB;0, and FP$SUB and FP$ADD from the 
library) linked together. 

This example illustrates why the subtract module (FP$SUB) was placed before the add 
module (FPSADD). The linker scans the modules of a library only once, in a front-to-back 
order. If FP$SUB had been located after FPSADD, then the linker would not have found the 
definition for the FP.AD2 symbol after linking in FP$SUB. 
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TEKDOS SVC GENERATION 

This example explores two areas of TEKDOS service cails: creating service request blocks 
(SRBs), and generating the required microprocessor service call (SVC) instructions. This 
example uses the 8080A/8085A instruction set, but similar techniques can be applied to 
most processors. 

This example assumes you are familiar with the use of SVCs under TEKDOS, as described in 
the Service Calls section of the 8002A System Users Manual, 



\zi63IinQ ^@rVBC6 fi©Cl!J©ST oiOCKS 

The first task in using an SVC is to create an appropriate SRB. The SRB consists of eight 
bytes: 

1 . a function code, 

2. a channel number, 

3. a status byte, 

4. a single-byte data item, 

5. a byte count for I/O operations, 

6. a buffer length, 

7. the high-order byte of the buffer address, and 

8. the low-order byte of the buffer address. 

The buffer (specified by the last three bytes) is used for I/O operations. 

Setting up the SRB in your source program can be made easier when you use an 
"intelligent" macro. The macro can decide (based on the parameters you give it) whether to 
generate a SRB location vector, what the names of the SRB components are, what the size of 
the I/O buffer is, and other miscellaneous items. The following assembler source statements 
define a macro that performs these functions. A line-by-line description follows the listing. 
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The SRB Macro 





STRING 


SRB$SEC(8), SI 




MACRO 


SRB 


SRB$SEC 


SET 


ti » « * ti 




IF 


DEF(SRB.SEC) 




RESUME 


SRB. SEC 




ELSE 






SECTION 


SRB. SEC 




ENDIF 




•1 • .FUN 


BLOCK 


1 


• 1 ' .CHN 


BLOCK 


1 


•1 ' .STA 


BLOCK 


1 


' 1 » .DAT 


BLOCK 


1 


'1 ' .CNT 


BLOCK 


1 




IF 


II 1 O 1 II _ II II 


'1 • .LEN 


BLOCK 


1 


•1 • .HIB 


BLOCK 


1 


' 1* .LOB 


BLOCK 
ELSE 


1 




IF 


II 1 ij 1 II _ II II 


SRB$BUF 


SET 
ELSE 


"' 1 ' .BUF" 


SRB$BUF 


SET 
ENDIF 


ii i i| i it 


• 1 ' .LEN 


BYTE 


'3' 


' 1' .HIB 


BYTE 


HI( 'SRB$BUF' ) 


•1 ' .LOB 


BYTE 


LO('SRB$BUF' ) 




IF 


DEF(BUF.SEC) 




RESUME 


BUF. SEC 




ELSE 






SECTION 


BUF. SEC 




ENDIF 




'SRB$BUF' BLOCK 


.3, 




ENDIF 






IF 


n 1 2 * « <> " " 




IF 


DEF(SRB.VEC) 




RESUME 


SRB.VEC 




ELSE 






SECTION 


SRB.VEC, ABSO 




ENDIF 






ORG 


40H+2*('2 f -1) 




BYTE 


HIC1 • .FUN) 




BYTE 


LOC1 ' .FUN) 




ENDIF 






RESUME 


•SRB$SEC» 




ENDM 





line 


1 


line 


2 


line 


3 


line 


4 


line 


5 


line 


6 


line 


7 


line 


8 


line 


9 


line 


10 


line 


11 


line 


12 


line 


13 


line 


14 


line 


15 


line 


16 


line 


17 


line 


18 


line 


19 


line 


20 


line 


21 


line 


22 


line 


23 


line 


24 


line 


25 


line 


26 


line 


27 


line 


28 


line 


29 


line 


30 


line 


31 


line 


32 


line 


33 


line 


34 


line 


35 


line 


36 


line 


37 


line 


38 


line 


39 


line 


40 


line 


41 


line 


42 


line 


43 


line 


44 


line 


45 



Explanation of the SRB Macro 

The macro is invoked with the following parameters: 

1 . The first parameter is the name of the SRB. The name must be one to four characters 
long, and must be a valid symbol prefix. Many labels describing parts of the SRB and 
buffer are derived from this name. 

2. The second parameter is optional; if present, the parameter designates the SVC 
number (1 to 6) that will be used with this SRB. If you provide this number, the macro 
will create the appropriate pointer to this SRB in the 40H to 4BH area of memory. If 
you omit this parameter, you must use other assembler statements to supply the 
pointer. 



9-za 



fn) 



Programming Examples— 8002A: Assembler Users Manual TEKDOS SVC Generation 



3. The third parameter is optional; if present, the parameter designates the size of I/O 
buffer to be associated with this SRB. The last three bytes of the SRB are correctly 
altered to describe the buffer's size and location, and the buffer of this size is created. 
The name of the buffer is controlled by the fourth parameter. If you omit the third 
parameter, the last three bytes of the SRB are left empty. 

4. The fourth parameter is optional; if present, the parameter selects the name of the 
buffer associated with this SRB. If you omit this parameter, the macro chooses a name 
derived from the SRB name. This parameter will be ignored if the third parameter is 
not present. 

Line 1 creates two string assembler variables: SRB$SEC and SRB$BUF. These variables are 
used within the body of the assembler macro to temporarily store data, so that it may be 
retrieved later in the macro. These variables are further discussed when they are used. 

Line 2 defines the beginning of the macro, and gives the macro the name SRB. 

Line 3 saves the current section name in the assembler variable SRB$SEC. The current 
section name is saved so that it may be restored later; the remaining statements in this 
macro switch sections at least once. 

Lines 4 through 8 switch the current section to SRB.SEC, so that later assembler statements 
can generate object bytes for an SRB. The IF statement determines whether or not the 
section SRB.SEC was previously started: if so, a simple RESUME statement is processed, to 
continue object code generation; if not, the section is begun with a SECTION statement, as 
its first definition. This technique of using IF DEF(section-name) to conditionally resume a 
section is used twice again, starting in lines 27 and 35. 

Lines 9 through 13 define the common part of the SRB. Each byte of the SRB is given a 
descriptive name (label). This label consists of the SRB name (given as the first parameter at 
invocation) followed by a four-character suffix. The suffix for each SRB byte indicates the 
function of that byte. For example, if the first parameter at macro invocation is QQ, then the 
five bytes generated by these five lines of code are: QQ.FUN (function), QQ.CHN (channel), 
QQ.STA (status), QQ.DAT (byte data), and QQ.CNT (I/O count). 

Lines 14 through 33 generate the last three bytes of the SRB, and create the buffer (if 
necessary). Three possible combinations exist: 

1 . No third parameter: the last three bytes of the SRB are generated like the first five — 
labels are generated and space is allocated, but no values are inserted into the SRB 
bytes. 

2. Third parameter only: The last three bytes of the SRB describe a buffer generated by 
this macro. The name of the buffer is derived from the name of the SRB, in the same 
way as the name of the SRB components. 

3. Both third and fourth parameters: Again, the last three bytes of the SRB describe a 
buffer generated by this macro, but the name of the buffer is explicitly given (by the 
fourth parameter). 

Line 14 examines the third parameter: if absent, lines 15 through 17 are assembled; if 
present, lines 19 through 32 are assembled. In either case, the other block of statements is 
skipped. 
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Lines 15 through 17 generate the last three bytes of the SRB when the third parameter is 
absent. Again, the names of the three bytes are derived from the SRB name given in the 
macro invocation line. If the SRB name is QQ, for example, three bytes are generated: 
QQ.LEN (length of buffer), QQ.HIB (high byte of the buffer address), and QQ.LOB (low byte of 
the buffer address). 

Lines 19 through 23 determine the name of the buffer. If the fourth parameter is absent, the 
name of the buffer is created from the SRB name; for example, an SRB name of QQ produces 
a buffer name of QQ.BUF. If a fourth parameter is present, then it is used as the buffer name. 
In either case, the buffer name is assigned to the assembler string variable SRB$BUF. This 
variable is used later in the macro. 

Lines 24 through 26 generate the last three bytes of the SRB, using the given size and name 
of the buffer. As with the other bytes of the SRB, each of these bytes is given a label derived 
from the SRB name. For example, a SRB name of QQ generates the labels QQ.LEN, QQ.HIB, 
and QQ.LOB. However, unlike the other bytes of the SRB, these bytes are given values at 
assembly time. Because the location and size of the buffer are known, the correct values can 
be given to these bytes. 

Lines 27 through 31 change the current section to BUF.SEC, using the method described 
previously (lines 4 through 8). Section BUF.SEC contains any I/O buffers generated by the 
macro. 

Line 32 generates the I/O buffer. The name is defined in the assembler string variable 
SRB$BUF. The size is taken from the third invocation parameter. 

Lines 34 through 43 generate a pointer to the SRB in the SRB vector (fixed locations 40H to 
4BH) only if the second parameter is present. 

Lines 35 through 39 define SRB.VEC as the current section. This section is absolute (non- 
relocatable), because the vectors must be in fixed locations in memory. 

Line 40 generates an assembler ORG directive to place the pointer in the proper location. 
The operand of the ORG directive computes an address from the second parameter in the 
invocation; this parameter is a digit from 1 to 6. 

Lines 41 and 42 generate a pointer to the SRB's first entry, the function byte. 

Line 44 restores the current section to the section name that was saved upon entry into this 
macro. 

Line 45 terminates the definition of the macro. 
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Sample Invocations of the SRB Macro 

The SRB macro can be invoked in many different ways, depending on the needs of the 

citiiation Fnr evflmnlp in itQ cimnifict im/nratinn 

SRB CfQQ 

only an SRB is generated. The name of the SRB is specified in the first parameter, QQQ. The 
SRB consists entirely of BLOCK assembler directives; your program is expected to place 
values into the various bytes of the SRB. 

The SRB macro can be invoked with an SVC number, like this: 

SRR RRR, 4 

The SRB macro automatically places the appropriate pointer to the SRB (named RRR) at 
locations 46H and 47H. Again, no part of the SRB is given a value at assembly time; your 
program must supply all values (including pointers to buffers) at program execution time. 

If you wish to specify a buffer, include the third and fourth parameters. For example, 

SRB SSS, , 128, BUFFER 

specifies a BUFFER that is 128 bytes long. This buffer is created automatically by the macro. 
The macro also places values (describing the location and length of the buffer) into the last 
three bytes of the SRB, relieving your program of this responsibility. 

If you do not require a specific buffer name, omit the fourth parameter. The name will be 
derived from the SRB name. You still specify the third parameter, to tell the macro the length 
of buffer to be created. For example, the macro invocation 

SRB TTT, , 64 

creates a 64-byte buffer named TTT.BUF. 

You can create the buffer and SRB pointer simultaneously by including all four parameters in 
the SRB macro. For example, the invocation 

SRB UUU, 3, 80, MYBUF 

creates an SRB named UUU, a pointer to the SRB at addresses 44H and 45H (the SVC 3 
vector location), and an 80-byte buffer named MYBUF. 



Generating Service Calls 

The task of generating the service call consists of placing two microprocessor-dependent 
instructions in your program. The first instruction is usually a data transfer instruction, while 
the second is a no-operation instruction. For an 8080A/8085A microprocessor, the OUT and 
NOP instructions are used for SVCs. 

You can use an assembler macro to assist you in creating the OUT/NOP instruction 
sequence. The following listing presents a sample macro. A line-by-line description follows 
the listing. 
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The SVC Macro 



MACRO 


SVC 


line 1 


IF 


ii i i t it _ nit 


line 2 


WARNING 


; Missing SVC Number 


line 3 


ELSE 




line 4 


OUT 


0F8H-M ' 


line 5 


NOP 




line 6 


ENDIF 




line 7 


ENDM 




line 8 



Explanation of the SVC Macro 

This macro is invoked with one parameter, the SVC number: a single digit between 1 and 6. 

Line 1 defines the name of the SVC-generation macro. 

Lines 2 through 7 form an IF. .ELSE. .ENDIF block. If the first parameter is absent, line 3 is 
processed. If the first parameter is present, lines 5 and 6 are processed. 

Line 3 (processed only if no first parameter is given) generates an error message. This 
message indicates that the required parameter has not been given in this invocation of the 
macro. The error message appears on the listing and the system terminal. 

Lines 5 and 6 generate an 8080A/8085A service call instruction sequence. Line 5 generates 
an OUT instruction; the address of the OUT instruction is computed from the first macro 
parameter. Line 6 generates the required NOP (no-operation) instruction. 

Line 8 terminates the macro definition. 



Sample Invocation of the SVC Macro 

The SVC macro is simple to invoke: simply provide the SVC number as the first parameter. 
For example, 

SVC 4 

generates the proper instruction sequence for SVC 4. If the first parameter is omitted, an 
error message is generated. 



CREATING CONSTANT VALUES 

This example illustrates the use of a macro to declare a constant value in a separate 
assembler section. In this example, two versions of the macro are shown: one to define 
values to be stored in ROM, and the other to define values to be stored in RAM. By using 
these two macros, you can store constants in either ROM or RAM from anywhere within 
your program. 

Here's how the macro works: first, it switches from the current section to an alternate 
section. Then, it generates the object code for the statements specified. It ends by switching 
back to the original section. By using statements with data storage directives (such as ASCII, 
BYTE, BLOCK, and WORD), you can store values in the alternate section. 
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Creating Constant Values 



The macro may be invoked by one of two methods: 

• Method 1. The statement lines to be assembled in the alternate section are passed as 
nararngters in the o n erand field of the macro invocation, 

• Method 2. The statement lines to be assembled in the alternate section are a sequence 
of lines following the macro invocation. The macro invocation has no parameters in the 
operand field. The invocation of a second macro terminates the sequence of lines and 
resumes the original section. 

Sample invocations are presented later in this example. 



The CONSTANT Macro 

This version of the macro stores values in a section ROM. CODE, which can be assigned to 
ROM memory at link time. 





STRING 


CON$SAVE,CON$SEC ; 


line 1 


CON$SEC 


SET 


"ROM. CODE" ; 


line 2 




MACRO 


CONSTANT ; 


line 3 


C0N$SAVE 


SET 


H 1 J t 1) 


line 4 




IF 


DEF(»CON$SEC) ; 


line 5 




RESUME 


•C0N$SEC 


line 6 




ELSE 




line 7 




SECTION 


•CON$SEC 


line 8 




ENDIF 




line 9 




IF 


•#• 


line 10 


C0N$CNT 


SET 


1 


line 11 




REPEAT 


CON$CNT <= '#' 


line 12 


•CON$CNT' 






line 13 


CON$CNT 


SET 


CON$CNT + 1 


line 14 




ENDR 




line 15 




ENDCONSTANT 


; line 16 




ENDIF 




line 17 




ENDM 




; line 18 




MACRO 


ENDCONSTANT 


line 19 




RESUME 


»CON$SAVE' 


; line 20 




ENDM 




line 21 



Line 1 creates two string assembler variables, CON$SAV and CON$SEC. These variables are 
used within the body of the macro to temporarily store data. 

Line 2 assigns the character string "ROM.CODE" to the variable CON$SEC. The variable is 
used for the name of the section in which the constants are stored. 

Line 3 defines the beginning of the macro and gives it the name CONSTANT. 

Line 4 saves the current section name in the variable CON$SAVE so that it may be resumed 
later. 

Lines 5 through 9 switch the current section to the section ROM.CODE (the value of the 
variable CON$SEC). The IF statement determines whether or not the section ROM.CODE was 
nrowinnciu HofinoH /ctartprn- if <?o the RFSUME statement (line 6) continues the section 
definition; if not, the SECTION statement (line 8) begins the section definition. 



(O) 
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Line 10 tests for the presence of a parameter. The assembler replaces the construct '#' with 
the number of parameters in the macro invocation line. If the parameter count is non-zero, 
the assembler processes lines 11 through 16. Otherwise, the assembler skips to line 18. 

Line 11 initializes the assembler variable CON$CNT to designate the first parameter. This 
variable is incremented later (line 14) for each parameter. 

Lines 12 through 15 form a conditional repeat block. In this block, the invocation parameters 
are processed within the macro. The first time the repeat loop is processed, the value of 
CONSCNT is 1, and the construct 'CON$CNT' (in line 13) is replaced by the first parameter. 
As CON$CNT is incremented (line 14), each successive parameter is processed, until the 
value of CON$CNT exceeds the number of parameters passed ('#' in line 12). 

Line 16 invokes the macro ENDCONSTANT, which is defined in lines 19 to 21. 

If '#' was zero in line 1 0, the assembler proceeds to line 1 8 (the first statement following the 
ENDIF). This statement terminates the macro. The assembler will then process the next 
statement lines following the invocation of the CONSTANT macro. These statements provide 
data for section ROM. CODE. The statement lines will continue to be processed within section 
ROM. CODE until macro ENDCONSTANT is invoked. 

Line 19 through 21 define macro ENDCONSTANT. The macro ENDCONSTANT simply 
switches the current section back to the section name that was saved at the beginning of this 
macro (line 4). 

The VARIABLE Macro 

A similar macro can be created to store variables in RAM. The section RAM. CODE can be 
assigned to RAM memory at link time. 

STRING VAR$SAVE, VAR$SEC 

VAR$SEC SET "RAM. CODE" 

MACRO VARIABLE 

VAR$SAVE SET "'J'" 

IF DEF( 'VAR$SEC ) 

RESUME 'VAR$SEC 

ELSE 

SECTION »VAR$SEC 

ENDIF 

IF '#' 
VAR$CNT SET 1 

REPEAT VAR$CNT <= '#' 
'VAR$CNT' 
VAR$CNT SET VAR$CNT + 1 

ENDR 

END VARIABLE 

ENDIF 

ENDM 
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The ENDVARIABLE macro definition is: 

MACRO ENDVARIABLE 
RESUME »VAR$SAVE' 
ENDM 



Macro Invocation 

Assume that you would like to store a character string in a section of ROM memory and call 
a routine to print that character string. (This example assumes that your program supplies a 
subroutine PRINT. The subroutine prints each successive character pointed to by the HL 
register until a return character is encountered.) The following invocation of the macro 
CONSTANT could be used to store the message to be printed. 

SECTION PRINCON 

LXI H,MES1 

CONSTANT MES1 ASCII "HELLO THERE" , [ BYTE 133 

1 st parameter 2nd parameter 

CALL PRINT 

The first line declares section PRINCON. 

The second line is an 8080A/8085A instruction that loads the HL register with a pointer to 
MES1. 

The third line invokes the macro CONSTANT with two parameters. The first parameter is an 
assembler statement that stores the ASCII representation of the character string "HELLO 
THERE" and has the location MES1. The second parameter [ BYTE 13] generates one byte of 
data with the value 13 (the ASCII return character). The space in the first position of the 
parameter causes the BYTE to be treated as an assembler directive, and not as a label. These 
two lines are processed within the section ROM. CODE. The macro then switches back to the 
section PRINCON. 

The last line of this example, CALL PRINT, invokes the subroutine PRINT. 

Macro CONSTANT simply switches to section ROM. CODE when you do not supply any 
parameters. Any assembler statements between the invocation of CONSTANT (without 
parameters) and a matching invocation of ENDCONSTANT are generated into section 
ROM. CODE. For example, the following assembler statements produce identical results to 
the previous example: 

SECTION PRINCON 

LXI H,MES1 
CONSTANT 

MES1 ASCII "HELLO THERE" 

BYTE 13 
ENDCONSTANT 

CALL PRINT 

111 B.IUO IMVUUUHUI I, II IQ IIIVVOULIUII \S I 

and resumes the original section. 
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With the use of macro VARIABLE, you could establish a data block in a section destined for 
RAM. In this example, the symbol DATA.TAB points to a block of 512 bytes. The macro can 
be invoked with either this sequence of statement lines: 



LXI 

VARIABLE 

CALL 



or this sequence: 



LXI 
VARIABLE 
DATA.TAB BLOCK 512 
ENDVARIABLE 
CALL PROCESS 



H, DATA. TAB 
DATA.TAB BLOCK 512 
PROCESS 



H, DATA. TAB 



SAVE-AND-RESTORE MACRO 

This example uses two assembler macros in a common assembly language operation: saving 
and restoring microprocessor registers. The example uses the 8080A/8085A instruction set; 
however, the techniques illustrated here can be applied to nearly all stack-oriented 
microprocessors. 



The SAVE Macro 





MACRO 


SAVE 




line 1 




IF 


'#' 




line 2 


SAVE$ 


SET 


1 




line 3 




REPEAT 


SAVE$ <= 


'#• 


line 4 




PUSH 


'SAVE$' 




line 5 


SAVE$ 


SET 

ENDR 

ELSE 


SAVE$ + 


1 


line 6 

line 7 

; line 8 




SAVE 


B, D, H, 


PSW 


line 9 




ENDIF 






; line 10 




ENDM 






line 11 



This macro is used to save one or more registers on the stack. The parameters of the macro 
invocation line designate the registers to be saved on the stack. The body of this macro 
examines those parameters and generates the appropriate 
instructions. 



8080A/8085A PUSH 



Line 1 begins the macro definition, and gives the macro the name SAVE. This name will be 
used later in the program to invoke the macro. 

Line 2 begins an lF..ELSE..ENDiF block. This iF statement has one operand: the construct '#'. 
The assembler will replace this construct with the number of parameters present in the 
macro invocation line. If the parameter count is non-zero, the assembler processes all 
statements between this IF statement and the corresponding ELSE statement (line 8). If the 
parameter count is zero (meaning that the invocation statement consisted solely of the word 
SAVE), the assembler processes the statements between the ELSE and ENDIF statements. 
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Save-and-Restore Macro 



Lines 3 through 7 are processed if the macro invocation includes one or more parameters. 
The macro must generate one PUSH instruction for each parameter provided; each 
parameter is the name of one 8080A/8085A register pair. A REPEAT.. ENDR loop processes 
each parameter in turn. 

Line 3 initializes the assembler variable SAVE$ to 1. This assembler variable will be 
incremented once for each parameter given in the macro invocation line. 

■ : a a~~:~~~*~^ +!-.,% kanlnninn nf tha DCPCAT CMHR loo" Thp Inrtrt ic ror»satf»H a<z Innn a<5 

1_II1C *t ucaiyiiaioo mc ucy i iy ui inv/ i»i_i i_«-» i ..i_i<«^i i iv^vJj^. nic .^^; K .0 '«f-'«-'- — ~ -53 

the assembler variable SAVE$ is not greater than the number of parameters passed to the 
macro ('#'). 

Line 5 generates an 8080A/8085A PUSH instruction. The operand of the PUSH instruction 
is obtained from the current value of SAVES. For example, if SAVES is 3, and the third 
parameter in the macro invocation is H, this statement generates an 8080A/8085A PUSH H 
instruction. 

Line 6 increments the value of the assembler variable SAVES. 

Line 7 terminates the definition of the REPEAT.. ENDR loop. As long as the expression 
specified in the REPEAT statement is true (non-zero), the assembler will process the group of 
statements within the REPEAT.. ENDR block. 

Line 8 terminates the IF. .ELSE block. 

Line 9 is processed only when the IF condition (in line 2) is false (zero). If SAVE is entered 
with no parameters, the SAVE macro reinvokes itself with ail four possible parameters, 
thereby saving all four register pairs. 

Line 10 terminates the IF..ELSE..ENDIF block. 

Line 1 1 statement terminates the definition of the macro. 



The RESTORE Macro 

MACRO RESTORE 



r 



IF 
REST0RE$ SET 

REPEAT 

POP 
REST0RE$ SET 

ENDR 

ELSE 

RESTORE PSW, H, D, 

ENDIF 

ENDM 



1 

RESTORE! <= '# 

'REST0RE$' 

RESTORE! + 1 



(0) 
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The RESTORE macro is similar to the SAVE macro, with two changes: 

1. The assembler variable is named RESTORES in this macro. 

2. The order of the registers in the default macro invocation (no parameters) is reversed. The 
stack operates in a last-in-first-out (LIFO) manner: the last register saved must be the first 
register restored. 

Sample Invocations 

The SAVE and RESTORE macros are most commonly used at the beginning and end of 
subroutines to insure that the subroutine does not destroy values in the registers needed by 
the calling routine. For example, if all registers are used in a subroutine, you can include the 
SAVE macro invocation (with no parameters) at the subroutine's beginning, and the 
RESTORE macro invocation (again, with no parameters) at the subroutine's end, like this: 

SUBR SAVE ; Beginning of subroutine SUBR; save all registers 

... ; Body of the subroutine 

RESTORE ; Restore all registers 

RET ; 8080A/8085A return-from-subroutine instruction 

If some (but not all) registers are used in the subroutine, you can invoke SAVE and RESTORE 
with a list of those registers to be saved on the stack. Note that the order of the registers 
must be reversed when restoring them from the stack. 

SUBR SAVE H, PSW ; Save H-L and PSW-A 

... ; Body of subroutine 

RESTORE PSW, H ; Restore PSW-A, H-L 

RET ; Return from subroutine 

CONDITIONAL ASSEMBLY 

This example illustrates some uses of the IF-ELSE-ENDIF or IF-ENDIF constructs for 
conditional assembly. 

Three typical examples are provided: (1) processor-independent programming, (2) use of 
conditional assembly in macros, and (3) assembly based on relative memory locations. 
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Conditional Assembly 



Processor-Independent Programming 

A program may be written to run on two or more similar processors by placing the processor- 
dependent instructions in conditional biocks. These conditional blocks check the processor 
type and assemble the correct instructions. 

MACRO SUBTRACT 
; This is a processor-independent macro written for either the Z80 or the 8085 

If processor is a Z80... 
Clear the accumulator 
Subtract DE from HL 
But, if not a Z80. . . 
If processor is an 8085A 
Transfer L to A 
Subtract E from A 
Move A to L 
Move H to A 

Subtract (carry+D) from A 
Move A to H 
But, if not 8085. . . 
WRONG PROCESSOR - 'PROC 



IF 


PROC="Z80" 


OR 


A 


SBC 


HL,DE 


ELSE 




IF 


PROC="8085" 


LD 


A,L 


SUB 


E 


LD 


L,A 


LD 


A,H 


SBC 


D 


LD 


H,A 


ELSE 




WARNING 




ENDIF 




ENDIF 





Use of Conditional Assembly in Macros 

Conditional assembly is used primarily in macros. The main body of the program is usually 
structured such that, once it is written, few changes will need to be made. Macros, however, 
are designed to examine their parameters, and make decisions which may vary with 
programming and run-time conditions. 

One use of conditional assembly in macros is to assemble statements only upon the first 
invocation of the macro. For example, an error will occur if a string variable is defined more 
than once; the following structure may be used to check for previous definitions. 



IF \DEF(STRI) 

STRING STRK100) 
ENDIF 



IF STRI HAS NOT BEEN DEFINED 
DEFINE STRI OF 100 



These instructions will determine whether or not the string variable STRI has been defined 
previously. If it has not, the statement STRING STRI(100), which defines a string variable 
named STRI of 100 characters, is assembled. 

Another use of conditional assembly in macros is to verify that a symbol has previously been 
declared as a global symbol. 



If PRINT has not been defined yet, 
Define PRINT as a global 
Continue with rest of macro 
Move first parameter to A 
Move second parameter to BC 



MACRO 


CALLPRINT 


IF 


XDEF(PRINT) 


GLOBAL 


PRINT 


ENDIF 




LD 


A, M ' 


LD 


BC, '2' 


CALL 


PRINT 


ENDM 





The conditional block in this macro checks if PRINT has been defined as a global symbol. If 
PRINT has not been defined, the statement GLOBAL PRINT is assembled. If PRINT has been 
defined previously, the statement in the conditional block is skipped. 



(a) 
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Assembly Based on Relative Memory Locations 

Conditional assembly can also be used to keep track of the relative distance between bytes of 
memory; this information may then be used to decide which instructions to assemble. For 
example, the Z80 JR (jump relative) instruction will not allow a jump of more than 1 28 bytes. 
The relative distance between bytes must be less than +128 and greater than -127. If the 
range is exceeded, a warning will be issued. The following example checks to see if the 
relative distance between the location counter and the jump address is within the specified 
range. If it is, the JR instruction is assembled: if not, the JP instruction, which has no range 
restriction, is assembled. 



IF 

IF 

JR 

ELSE 

WARNING 

JP 

ENDIF 

ELSE 

JP 

ENDIF 



forward reference 
: and it's near 



DEF(LABEL) ; If the label is not a 
(($-LABEL) > -127) & (($-LABEL) < +128) 
LABEL ; do a JR 

; Not close enough, so tell user. 
RANGE EXCEEDED. JP INSTRUCTION USED INSTEAD 

; and generate the JP 



; JR 
LABEL 



LABEL 



Forward reference? 
Always a JP (can' t 



tell where it is) 



This conditional block may be inserted into a macro and invoked when the jump instruction is 
needed. When the macro is assembled and executed, the correct jump instruction will be 
assembled into the object file. 

NAME MAINPRO 



MACRO JUMP ; BEGINS MACRO JUMP DEFINITION 

IF DEF(M') 

IF (($-M») > -127) & (($-'1') < +128) 

JR '1 • 

ELSE 

WARNING ; JR RANGE EXCEEDED. JP INSTRUCTION USED 

JP ' 1 ' 

ENDIF 

ELSE 

JP '1 ' 

ENDIF 

ENDM ; END OF MACRO DEFINITION 



JUMP LABEL ; INVOKES THE MACRO JUMP WITH THE PARAMETER "LABEL" 



@ 
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Using the '@' Construct within Macros 



USING THE '@' CONSTRUCT WITHIN MACROS 

This example illustrates the use of the '@' (at) construct in macros. Each time a macro is 
invoked, an v '@' construct appearing in the macro body is replaced with a unique four- 
character value. When this value is appended to a one-to-four character symbol within the 
macro body, a unique five-to-eight character label is created. With this construct, you can 
use a label symbol within a macro. Even though the macro is invoked more than once, the 
label symbol is unique for each invocation. 

The example shown here is a deiay ioop that uses the '@' construct for two separate label 
symbols. Even though this macro is invoked more than once, DEL1'@' and DEL2'@' will be 
unique each time the macro is invoked. 

The number of delay loops (0 to OFFH) is passed to the macro DELAY as the single parameter. 



This example uses the 8080A/8085A instruction set, but similar techniques can be applied 
to most processors. 



Delay Loop Macro 





MACRO 


DELAY 


line 1 




MVI 


H, ' 1 • 


line 2 


DEL2'@' 


MVI 


L,0FFH 


line 3 


DEL1»§' 


DCR 


L 


line 4 




JNZ 


DEL1 '§' 


line 5 




DCR 


H 


line 6 




JNZ 


DEL2'@» 


line 7 




ENDM 




; line 8 



Line 1 defines the beginning of the macro and names it DELAY. 

Line 2 is an assembly language instruction that moves the value of the parameter (number of 
delay loops) to the H register. 

Line 3 moves the value OFFH into the L register. The label DEL2'@' is replaced by a unique 
eight-character symbol each time the macro is invoked. 

Line 4 decrements the L register. The label DEL1'@' is replaced by another unique symbol. 

Line 5 tests the L register. If it is not zero, the program jumps to the DCR L (line 4) 
instruction. When the L register becomes zero, the program proceeds to the instruction DCR 
H (line 6). 

Line 6 decrements the H register (the number of delay loops requested). 

Line 7 tests the H register. If it is not zero, the program jumps to the MVI L,0FFH instruction 
(line 3), thus repeating the DEL1'@' loop the number of delay loops requested. When the H 
re n ister becomes zero, the macro is terminated. 
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Macro Invocation 

DELAY 10H 



SHORT DELAY 



DELAY 



OFFH 



LONG DELAY 



In this example, the first time macro DELAY is invoked the number of delay loops is 10H. The 
label symbols DEL2'@' and DEL1'@' represent one set of address values. When DELAY is 
invoked again with OFFH delay loops requested, DEL2'@' and DEL1'@' represent another set 
of addresses. 

THE ASSEMBLER INCLUDE DIRECTIVE 

This example illustrates some uses of the INCLUDE directive. The INCLUDE directive causes 
the assembler to process statements from the specified file as though they were a part of 
your source file. 

Frequently used blocks of code and macro definitions may be stored in disc files. These 
statements may be included in programs when needed, by simply entering the INCLUDE 
directive and the file name. The contents of the file is then assembled into the object module. 

This example illustrates four ways in which the INCLUDE directive may typically be used: (1 ) 
defining constants, (2) defining COMMON sections, (3) defining macros, and (4) providing 
authorship notices in your listings. 



Including Constant Declarations 

If you're using the same set of constants for a number of programs, you may store them in a 
disc file. You can INCLUDE them in your program, where they'll be processed with your 
source statements at assembly time. This feature can save you a great deal of time. For 
example, a file named CONST contains the constant definition block listed below. 



ROWS 
COLS 



EQU 
EQU 



20 
15 



Defines the number of rows 
Defines the number of columns 



The main program, which uses this block of constants, is shown below. 



NAME MAINPRO 

INCLUDE "CONST" 
MVI B,R0WS 

MVI C,C0LS 



Constant definitions 
Number of rows to B 
Number of columns to C 



TABLE 



BLOCK 



R0WS*C0LS ; Allocates space for a 300-byte table 
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The Assembler INCLUDE Directive 



When the nmnram MAINPRO is assembled, the constant definitions are included and the 
program looks like this. 



INCLUDE "CONST" 

ROWS EQU 20 

COLS EQU 15 

MVI B,R0WS 

MVI C,C0LS 



Defines the number of rows 
Defines the number of columns 
Number of rows to B 
Number of columns to C 



TABLE BLOCK ROWS*COLS ; Allocates space for a 300-byte table 



Including COMMON Declarations 

A group of COMMON statements is usually used in more than one program. You may store 
these statements in a disc file and include them in the various programs that require the 
same COMMON declarations. 



A file named COMM contains the COMMON declarations for the program MAINPRO. 



COMMON 
CNAME BLOCK 
ADDRESS BLOCK 
CITY BLOCK 

STATE BLOCK 



CUSTOMER 

30 

30 

16 

2 



Defines a COMMON section named CUSTOMER 
Reserves 30 bytes for CNAME 
Reserves 30 bytes for ADDRESS 
Reserves 16 bytes for CITY 
Reserves 2 bytes for STATE 



MAINPRO is the program which uses the COMMON declarations from the file COMM. 

NAME MAINPRO 

INCLUDE "COMM" : Defines the COMMON section 



When MAINPRO is assembled, the object module will contain the COMMON declarations as 
follows: 



NAME MAINPRO 

INCLUDE "COMM" 
COMMON CUSTOMER 



CNAME BLOCK 30 

ADDRESS BLOCK 30 

CITY BLOCK 16 

STATE BLOCK 2 



Defines a COMMON section named CUSTOMER 
Reserves 30 bytes for CNAME 
Reserves 30 bytes for ADDRESS 
Reserves 16 bytes for CITY 
Reserves 2 bytes for STATE 



& 
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MACRO 


ABC 


BYTE 


'1 ' 


WORD 


40 


ENDM 





The INCLUDE Directive in Macros 

The INCLUDE directive can be very helpful in assembly language programming. A frequently 
used macro may be defined in a disc file for later invocation. 

In this example, file MABC contains the macro definition to be included in the program 
MAINPRO. The BYTE directive has a parameter which will be given when the macro is 
invoked. 

Beginning of macro definition 
Generate a byte of the first parameter 
Generate a word containing 40 
End of macro definition 

MAINPRO, the program which includes the file MABC for its macro definition, is listed below. 

NAME MAINPRO 

INCLUDE "MABC" ; INCLUDES the definition for macro ABC 

ABC 5 ; Invokes ABC with a parameter of 5 

ABC 15 ; Invokes ABC with a parameter of 15 



Once the macro has been INCLUDEd in MAINPRO, each invocation of macro ABC will cause 
the macro to be expanded at assembly time. 



Authorship and Copyright Notices for Listings 

The INCLUDE directive may also be used to print authorship and copyright notices on 
program listings. 

Let's say that a file named COPYR contains the heading information that you wish to place 
on each program listing. 
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The Assembler INCLUDE Directive 



XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 

* COPYRIGHT (C) 1980 BY * 

X * 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

* * 
X ***#*** * * * * 

XXXX X 

* * XXX X X XXXX XXXX XXXX XXXX XXX X 
X XXXXXX X X xxxxxx a<> X 
X X XXXX XXX X X X xxxxx . R . * 
X XX XXX X x xxxxxx <<a X 
X X XXXXXXXX X XXX X XXXX XXXXX X 
X X 

* COMMITTED TO EXCELLENCE * 

X X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X X 

* TEKTRONIX, INCORPORATED, BEAVERTON, OREGON 97077 * 

X X 

* ALL RIGHTS RESERVED * 
x x 

XXXXXXXXXXXXXXXXXXXXXXXXXXXKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X X 

* AUTHOR: KEN DEDATE * 

X X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 



By using a single statement, INCLUDE "COPYR", your assembler listing will take the 
following format. 

NAME MAINPRO 

INCLUDE "COPYR" 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X * 

* COPYRIGHT (C) 1980 BY * 

X * 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 



xxxxxxx 

X 
X 
X 
X 
X 
X 



XXX 
X X 
XXXX 
X 



X 

X 

X X 

X X 

XXX 

X X 



XXXXXXXX 



X X 

X 

XXXX XXXX XXXX XXXX XX X 

X X X xxxxxx 

X X X xxxxx 

X X X xxxxxx 

XXX X XXXX X XXX X 

COMMITTED TO EXCELLENCE 



R . 



xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X * 

* TEKTRONIX, INCORPORATED, BEAVERTON, OREGON 97077 * 

X * 

* ALL RIGHTS RESERVED * 
x * 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X * 

* AUTHOR: KEN DEDATE * 

X * 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 



^ 



9-45 



8002A: Assembler Users Manual 



Section 10 

TARI.FS 



Table Page 
No. 

1 0-1 Source Module Character Set 10-1 

1 0-2 Assembler Directives 1 0-3 

1 0-3 ASCII Codes (Hexadecimal) 10-5 

1 0-4 Decimal-Hexadecimal-Binary Equivalents 1 0-6 

1 0-5 Hexadecimal Addition 1 0-7 

1 0-6 Hexadecimal Multiplication 1 0-8 
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Section 10 
TABLES 



Table 10-1 
Source Module Character Set 



Symbols 



Definition 



A..Z 

0..9 
$ 



, (comma) 



% 



letters used in symbols; lowercase characters (other than in strings and 
comments) are interpreted as the corresponding uppercase characters 

numbers used in symbols and constants 

used in symbols, and to represent assembler location counter contents 

used in symbols 

precedes a comment 

delimiter for operand items 

string delimiter 

string concatenation operator 

string substitution delimiter 

total number of arguments passed to current macro expansion 

treat everything within brackets as a single argument 

provide unique labels for each macro expansion 

replaced by name of current section in a macro expansion 

binary arithmetic operation, multiplication 

binary arithmetic operation, division 

unary or binary arithmetic operator, addition 

unary or binary arithmetic operator, subtraction 

override precedence of operators 



@ 
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Table 10-1 (cont) 



Symbols 


Definition 


\ 


unary log 


cal operator, NOT 


& 


binary log 


ical operator, AND 


! 


binary log 


ical operator, inclusive OR 


n 


binary log 


ical operator, exclusive OR 


SPACE 


field delimiter 




TAB 


field delimiter 




CARRIAGE 


field and 


line delimiter 


RETURN 








A 


allow following special character to have literal meaning 


AA 


allow the 


second i 


p-arrow character to have literal meaning 


= 


relational 


operator, 


equal 


<> 


relational 


operator, 


not equal 


> 


relational 


operator, 


greater than 


< 


relational 


operator, 


less than 


>= 


relational 


operator, 


greater than or equal 


<= 


relational 


operator, 


less than or equal 
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Table 10-2 
Assembler Directives 



Directive 


Operation 


ASCII 


generates ASCII data 


BLOCK 


reserves a data block 


BYTE 


generates byte(s) of data 


COMMON 


declares program section., assigns name, defines type to be common 


ELSE 


when the expression in the IF statement is false (zero), causes assembly 




of alternate source lines between ELSE and ENDIF directives 


END 


marks the end of an assembly source module 


ENDIF 


marks the end of an IF block 


ENDM 


marks the end of a macro 


ENDR 


marks the end of a REPEAT block 


EQU 


assigns a value to a symbol(s) 


EXITM 


terminates macro expansion before the ENDM 


GLOBAL 


declares global symbol 


IF 


when expression is true (non-zero), causes assembly of source lines 




between IF and ENDIF (or ELSE, if present) directives 


INCLUDE 


inserts text from another source file 


LIST 


turns on assembler listing options 


MACRO 


defines the beginning of a macro source block 


NAME 


declares object module name 


NOLIST 


turns off assembler listing options 


ORG 


assigns an address to the assembler location counter 


PAGE 


advances listing to a new page 


REPEAT 


causes source statements to be assembled repeatedly 



@ 
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Table 10-2(cont) 



Directive 



RESERVE 

RESUME 

SECTION 

SET 

SPACE 

STITLE 

STRING 

TITLE 

WARNING 

WORD 



Operation 



reserves a work space section 

resumes the definition of a section 

declares a program section, assigns name 

assigns or reassigns a value to a variable 

inserts blank lines in listing 

creates a listing page subtitle 

declares a string variable 

creates a listing page title 

displays a warning message 

generates word(s) of data 



10-4 



(5) 



Tables— 8002A: Assembler Users 



ASCI! Codes (Hexadecimal) 



Table 10-3 
ASCII Codes (Hexadecimal) 



HIGH-ORDER BITS 



LOW- 
ORDER 
BITS 








1 


2 


3 


4 


5 


6 


7 




miMTRni 


SYiymni s 


IIPPFRPASF 


LOWE RCASE 





NUL 


DLE 


SP 





@ 


P 


\ 


P 


1 


SOH 


DC1 


! 


1 


A 


Q 


a 


q 


2 


STX 


DC2 


„ 


2 


B 


R 


b 


r 


3 


ETX 


DC3 


# 


3 


C 


S 


c 


s 


4 


EOT 


DC4 


$ 


4 


D 


T 


d 


t 


5 


ENQ 


NAK 


% 


5 


E 


U 


e 


u 


6 


ACK 


SYN 


& 


6 


F 


V 


f 


V 


7 


BEL 

BELL 


ETB 


/ 


7 


G 


w 


9 


w 


8 


BS 

BACK SPACE 


CAN 


( 


8 


H 


X 


h 


X 


9 


HT 


EM 


) 


9 


I 


Y 


i 


y 


A 


LF 


SUB 


* 




J 


z 


J 


z 


B 


VT 


ESC 


+ 


» 


K 


[ 


k 


{ 


C 


FF 


FS 


- 


< 


L 


\ 


I 


■ 
1 


D 


CR 

RETURN 


GS 


- 


= 


M 


] 


m 


} 


E 


SO 


RS 




> 


N 


A 


n 


"N^ 


F 


SI 


US 


/ 


? 





- 


o 


DEL 

RUBOUT 
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Table 10-4 
Decimal-Hexadecimal-Binary Equivalents 





Hexa- 


Binary 




Hexa- 


Binary 




Hexa- 


Binary 




Hexa- 


Binary 


Deci- 


deci- 


8-bit 


Deci- 


deci- 


8-bit 


Deci- 


deci- 


8-bit 


Deci- 


deci- 


8-bit 


mal 


mal 


Code 


mal 


mal 


Code 


mal 


mal 


Code 


mal 


mal 


Code 





00 


0000 0000 


64 


40 


0100 0000 


128 


80 


1000 0000 


192 


CO 


1100 0000 


1 


01 


0000 0001 


65 


41 


0100 0001 


129 


81 


1000 0001 


193 


C1 


1100 0001 


2 


02 


0000 0010 


66 


42 


0100 0010 


130 


82 


1000 0010 


194 


C2 


1100 0010 


3 


03 


0000 001 1 


67 


43 


0100 0011 


131 


83 


1000 0011 


195 


C3 


1100 0011 


4 
5 


04 


0000 0100 


68 
69 


44 


0100 0100 


132 
133 


84 


1000 0100 


196 
197 


C4 


1100 0100 


05 


0000 0101 


45 


0100 0101 


85 


1000 0101 


C5 


1100 0101 


6 


06 


0000 0110 


70 


46 


0100 0110 


134 


86 


1000 0110 


198 


C6 


1100 0110 


7 


07 


0000 01 1 1 


71 


47 


0100 0111 


135 


87 


1000 0111 


199 


C7 


1100 0111 


8 


08 


0000 1000 


72 


48 


0100 1000 


136 


88 


1000 1000 


200 


C8 


1100 1000 


9 
10 


09 


0000 1001 


73 
74 


49 


0100 1001 


137 
138 


89 


1000 1001 


201 
202 


C9 


1100 1001 


0A 


0000 1010 


4A 


0100 1010 


8A 


1000 1010 


CA 


1100 1010 


11 


OB 


0000 1011 


75 


4B 


0100 1011 


139 


8B 


1000 1011 


203 


CB 


1100 1011 


12 


OC 


0000 1100 


76 


4C 


0100 1100 


140 


8C 


1000 1100 


204 


CC 


1100 1100 


13 


OD 


0000 1101 


77 


4D 


0100 1101 


141 


8D 


1000 1101 


205 


CD 


1100 1101 


14 
15 


OE 


0000 1110 


78 
79 


4E 


0100 1110 


142 
143 


8E 


1000 1110 


206 
207 


CE 


1100 1110 


OF 


0000 1111 


4F 


0100 1111 


8F 


1000 1111 


CF 


1100 1111 


16 


10 


0001 0000 


80 


50 


0101 0000 


144 


90 


1001 0000 


208 


DO 


1101 0000 


17 


11 


0001 0001 


81 


51 


0101 0001 


145 


91 


1001 0001 


209 


D1 


1101 0001 


18 


12 


0001 0010 


82 


52 


0101 0010 


146 


92 


1001 0010 


210 


D2 


1101 0010 


19 
20 


13 


0001 0011 


83 
84 


53 


0101 0011 


147 
148 


93 


1001 0011 


211 
212 


D3 


1101 0011 


14 


0001 0100 


54 


0101 0100 


94 


1001 0100 


D4 


1101 0100 


21 


15 


0001 0101 


85 


55 


0101 0101 


149 


95 


1001 0101 


213 


D5 


1101 0101 


22 


16 


0001 0110 


86 


56 


0101 0110 


150 


96 


1001 0110 


214 


D6 


1101 0110 


23 


17 


0001 0111 


87 


57 


0101 0111 


151 


97 


1001 0111 


215 


D7 


1101 0111 


24 
25 


18 


0001 1000 


88 
89 


58 


0101 1000 


152 
153 


98 


1001 1000 


216 
217 


D8 


1101 1000 


19 


0001 1001 


59 


0101 1001 


99 


1001 1001 


D9 


1101 1001 


26 


1A 


0001 1010 


90 


5A 


0101 1010 


154 


9A 


1001 1010 


218 


DA 


1101 1010 


27 


1B 


0001 1011 


91 


5B 


0101 1011 


155 


9B 


1001 1011 


219 


DB 


1101 1011 


28 


1C 


0001 1100 


92 


5C 


0101 1100 


156 


9C 


1001 1100 


220 


DC 


1101 1100 


29 
30 


1D 


0001 1101 


93 
94 


5D 


0101 1101 


157 
158 


9D 


1001 1101 


221 
222 


DD 


1101 1101 


1E 


0001 1110 


5E 


0101 1110 


9E 


1001 1110 


DE 


U01 1110 


31 


1F 


0001 1111 


95 


5F 


0101 1111 


159 


9F 


1001 1111 


223 


DF 


1101 1111 


32 


20 


0010 0000 


96 


60 


0110 0000 


160 


AO 


1010 0000 


224 


EO 


1110 0000 


33 


21 


0010 0001 


97 


61 


0110 0001 


161 


A1 


1010 0001 


225 


E1 


1110 0001 


34 
35 


22 


0010 0010 


98 
99 


62 


0110 0010 


162 
163 


A2 


1010 0010 


226 
227 


E2 


11100010 


23 


0010 0011 


63 


0110 0011 


A3 


1010 0011 


E3 


1110 0011 


36 


24 


0010 0100 


100 


64 


0110 0100 


164 


A4 


1010 0100 


228 


E4 


1110 0100 


37 


25 


0010 0101 


101 


65 


0110 0101 


165 


A5 


1010 0101 


229 


E5 


11100101 


38 


26 


0010 0110 


102 


66 


0110 0110 


166 


A6 


1010 0110 


230 


E6 


11100110 


39 
40 


27 


0010 0111 


103 
104 


67 


0110 0111 


167 
168 


A7 


10100111 


231 
232 


E7 


11100111 


28 


0010 1000 


68 


0110 1000 


A8 


1010 1000 


E8 


1110 1000 


41 


29 


0010 1001 


105 


69 


0110 1001 


169 


A9 


1010 1001 


233 


E9 


1110 1001 


42 


2A 


0010 1010 


106 


6A 


0110 1010 


170 


AA 


1010 1010 


234 


EA 


1110 1010 


43 


2B 


0010 1011 


107 


6B 


0110 1011 


171 


AB 


1010 1011 


235 


EB 


1110 1011 


44 
45 


2C 


0010 1100 


108 
109 


6C 


0110 1100 


172 
173 


AC 


1010 1100 


236 
237 


EC 


1110 1100 


2D 


0010 1101 


6D 


0110 1101 


AD 


1010 1101 


ED 


1110 1101 


46 


2E 


0010 1110 


110 


6E 


0110 1110 


174 


AE 


1010 1110 


238 


EE 


1110 1110 


47 


2F 


0010 1111 


111 


6F 


0110 1111 


175 


AF 


1010 1111 


239 


EF 


1110 1111 


48 


30 


001 1 0000 


112 


70 


0111 0000 


176 


BO 


1011 0000 


240 


FO 


1111 0000 


49 
50 


31 


001 1 0001 


113 
114 


71 


0111 0001 


177 
178 


B1 


1011 0001 


241 
242 


F1 


1111 0001 


32 


0011 0010 


72 


0111 0010 


B2 


1011 0010 


F2 


1111 0010 


51 


33 


0011 0011 


115 


73 


0111 0011 


179 


B3 


1011 0011 


243 


F3 


1111 0011 


52 


34 


0011 0100 


116 


74 


0111 0100 


180 


B4 


1011 0100 


244 


F4 


1111 0100 


53 


35 


001 1 0101 


I i r 


-re 

1 vJ 


0111 0101 


181 


B5 


1011 0101 


nAC 


1 o 


11-1-1 mm 


54 
55 


36 


0011 0110 


118 
119 


76 


0111 0110 


182 
183 


B6 


1011 0110 


246 
247 


F6 


1111 0110 


37 


0011 0111 


77 


0111 0111 


B7 


1011 0111 


F7 


1111 0111 


56 


38 


0011 1000 


120 


78 


0111 1000 


184 


B8 


1011 1000 


248 


F8 


1111 1000 


57 


39 


0011 1001 


121 


79 


0111 1001 


185 


B9 


1011 1001 


249 


F9 


1111 1001 


58 


3A 


0011 1010 


122 


7A 


0111 1010 


186 


BA 


1011 1010 


250 


FA 


1111 1010 


59 
60 


3B 


0011 1011 


123 
124 


7B 


0111 1011 


187 
188 


BB 


1011 1011 


251 
252 


FB 


1111 1011 


3C 


0011 1100 


7C 


0111 1100 


BC 


1011 1100 


FC 


1111 1100 


61 


3D 


0011 1101 


125 


7D 


0111 1101 


189 


BD 


1011 1101 


253 


FD 


1111 1101 


62 


3E 


0011 1110 


126 


7E 


0111 1110 


190 


BE 


1011 1110 


254 


FE 


1111 1110 


63 


3F 


0011 1111 


127 


7F 


0111 1111 


191 


BF 


1011 1111 


255 


FF 


1111 1111 
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Table 10-5 
Hexadecimal Addition 





1 


2 


3 


4 


5 


6 


7 


P m 


9 


A 


B 


C 


D 


E 


F 


1 


2 


3 


4 


5 


6 


7 


8 


Bin 


A 


B 


C 


D 


E 


F 


10 


2 


3 


4 


5 


6 


7 


8 


9 


cm 


B 


C 


D 


E 


F 


10 


11 


3 


4 


5 


6 


7 


8 


9 


A 


ffc 


C 


D 


E 


F 


10 


11 


12 


4 


5 


6 


7 


8 


9 


A 


B 


mm 


D 


E 


F 


10 


11 


12 


13 


5 


6 


7 


8 


9 


A 


B 


C 


Mm 


E 


F 


10 


11 


12 


13 


14 


6 


7 


8 


9 


A 


B 


C 


D 


iii 


F 


10 


11 


12 


13 


14 


15 


7 


8 


9 


A 


B 


C 


D 


E 


lit! 


10 


11 


12 


13 


14 


15 


16 


8 


y 


A 


B 


C 


D 


E 


F 


iii 


11 


12 


13 


14 


15 


16 


17 


9 


A 


B 


C 


D 


E 


F 


10 


ill! 


12 


13 


14 


15 


16 


17 


18 


A 


B 


C 


D 


E 


F 


10 


11 


iill 


13 


14 


15 


16 


17 


18 


19 


B 


C 


D 


E 


F 


10 


11 


12 


mm 


14 


15 


16 


17 


18 


19 


1A 


C 


D 


E 


F 


10 


11 


12 


13 


fill! 


15 


16 


17 


18 


19 


1A 


1B 


° 


E 


F 


10 


11 


12 


13 


14 


llli 


16 


17 


18 


19 


1A 


1B 


1C 


E 


F 


10 


11 


12 


13 


14 


15 


16 


17 


18 


19 


1A 


1B 


1C 


1D 


F 


!■ 


;M : : ; 


s :M:x 


::m. 


:m: 


±m 


v$m 


llli 


18 


19 


1A 


1B 


1C 


1D 


1E 



EXAMPLE 



HEX F + 8 = 17 



HEX 10 
HEX _7 
HEX 17 



16 DEC 

_L DE C 
23 DEC 



@ 
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Table 10-6 
Hexadecimal Multiplication 





1 


2 


3 


4 


5 


6 


7 


Si! 


9 


A 


B 


C 


D 


E 


F 


1 


1 


2 


3 


4 


5 


6 




mm 


9 


A 


B 


C 


D 


E 


F 


2 


2 


4 


6 


8 


A 


C 


E 


liil 


12 


14 


16 


18 


1A 


1C 


1E 


3 


3 


6 


9 


C 


F 


12 


15 


liil 


1B 


1E 


21 


24 


27 


2A 


2D 


4 


4 


8 


C 


10 


14 


18 


1C 


Ifc 


24 


28 


2C 


30 


34 


38 


3C 


5 


5 


A 


F 


14 


19 


1E 


23 


liil 


2D 


32 


37 


3C 


41 


46 


4B 


6 


6 


C 


12 


18 


1E 


24 


2A 


till 


36 


3C 


42 


48 


4E 


54 


5A 


7 


7 


E 


15 


1C 


23 


2A 


31 


Urn 


3F 


46 


4D 


54 


5B 


62 


69 


8 


8 


10 


18 


20 


28 


30 


38 


.:;:« 


48 


50 


58 


60 


68 


70 


78 


liil 


&*■■;. 


lili 


liil 


lii? 


nil 




1*1 


liil 


51 


5A 


63 


6C 


75 


7E 


87 


A 


A 


14 


1E 


28 


32 


3C 


46 


50 


5A 


64 


6E 


78 


82 


8C 


96 


B 


B 


16 


21 


2C 


37 


42 


4D 


58 


63 


6E 


79 


84 


8F 


9A 


A5 


C 


C 


18 


24 


30 


3C 


48 


54 


60 


6C 


78 


84 


90 


9C 


A8 


B4 


D 


D 


1A 


27 


34 


41 


4E 


5B 


68 


75 


82 


8F 


9C 


A9 


B6 


C3 


E 


E 


1C 


2A 


38 


46 


54 


62 


70 


7E 


8C 


9A 


A8 


B6 


C4 


D2 


F 


F 


1E 


2D 


3C 


4B 


5A 


69 


78 


87 


96 


A5 


B4 


C3 


D2 


E1 



EXAMPLE 



HEX 9x8 = 48 



HEX 40 
HEX _8. 
HEX 48 



64 DEC 
_§. DEC 
72 DEC 
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Section 1 1 
TECHNICAL NOTES 



This section is reserved for technical information about the TEKDOS Assembler, Linker, and 
Library Generator (LibGen). At the time of this writing, no technical notes are needed. 
Technical notes will be incorporated into later versions of this manual, as necessary. 
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Section 12 
ASSEMBLER SPECIFICS 



Processor-specific information is contained in the Assembler Specifics supplement that 
accompanies each assembler disc. Each supplement is designed as a subsection to this 
manual. 

These Assembler Specifics supplements are numbered as if they were separate sections of 
this manual. For example, the 6500/1 supplement is labeled "Section 12A," and the first 
illustration is numbered "Fig. 1 2A-1 ." Similarly, other supplements are labeled Sections 1 2B, 
12C, etc. Figures, pages, and tables are numbered accordingly. 

Each subsection presents the following information: 

• A demonstration run that parallels the one given for the 8080A/8085A in the Learning 
Guide of this manual. 

• A brief summary of the processor's addressing modes and registers. 

• A list of notational conventions used to describe the instruction set. 

• The microprocessor instruction set in a notation acceptable to the given assembler. 

• A list of reserved words for the given assembler. 

• The page size for the assembler, as defined in the Linker section of this manual. 

• Any processor-specific assembler error messages. 

• Any irregularities that should be noted. 
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Section 1 3 
ERROR MESSAGES 



INTRODUCTION 

This section lists the assembler error messages in numeric order. The assembler error 
messages with numbers above 92 are described in the Assembler Specifics section for your 
microprocessor. Refer to the Linker section for the linker error messages and to the Library 
Generator section for the LibGen error messages. Each error message is followed by a 
description of possible causes. 



***** ERROR 001:. (No message) This error is generated by a user-specified WARNING 
directive. For more information, see the WARNING directive in the Assembler Directives 
section of this manual. 



***** ERROR 002: Symbol already defined. A symbol has been redefined. This error may 
occur if the same symbol is equated to two different values (with EQU directives) or if two 
different instructions have the same label. 



***** ERROR 003: Symbol value Phase Error. There is a difference between pass 1 and 
pass 2 in the value or section number of a label or symbol. This message may be caused by a 
SET directive with a forward reference. 



***** ERROR 004: Illegal EQU of GLOBALs. An unbound global has been assigned the 
value of another unbound global (with the EQU directive). 



***** ERROR 005: Global definition may not use HI, LO. or ENDOF. The values of HI. LO 
or ENDOF have been assigned to a global symbol. This error may occur when a global symbol 
is equated to Hl(x) or L0(x), where x is an address; or ENDOF(y), where y is section name 
whose ending address is yet to be found. 



***** ERROR 006: String expression required. A numeric value appears where a string is 
required. Concatenation, SEG or NCHR functions, and ASCII, TITLE, or STITLE directives all 
require string operands. 
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***** ERROR 007: Undefined BLOCK or ORG expression. The operand of an ORG or 
BLOCK directive is either undefined or a forward reference. This error may occur if a 
misspelled or undefined symbol appears in an ORG or BLOCK directive, or if these directives 
reference a symbol that has not yet been assigned a value. 



***** ERROR 008: Invalid ORG out of section. The section of an ORG expression is either 
not a scalar or not an address within the current section. This error may occur if a misspelled 
or invalid symbol is used within an ORG expression or if a SECTION or RESUME statement is 
missing. 



***** ERROR 009: Negative block length. The BLOCK operand is either negative or greater 
than 32767. 



***** ERROR 010: Macro already defined. The same name appears in two or more 
MACRO directives. 



***** ERROR 01 1 : Macro definition phase error. There are two possible errors: the macro 
has been called before being defined, or the macro has been defined in the second (but not 
the first) pass of the assembler. This error may be caused by a forward reference used with a 
SET directive. 



***** ERROR 012: Memory full on Macro call. There is insufficient memory space to 
perform macro expansion. This error may occur if no limit is set for macro recursion, if too 
many symbols are used in a macro definition, or if too many actual parameters are specified. 



***** ERROR 013: Missing ENDR or ENDIF. A conditional assembly (IF or REPEAT) block 
is not properly terminated This error may occur if a conditional assembly block begins within 
a macro definition. This error may also occur if a macro ends (with the ENDM directive) 
before termination of conditional assembly (by the ENDR or ENDIF directive). 



***** ERROR 014: Duplicate definition of section name. A section name is already in use 
as a symbol. 
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*»*** frroR 015: END directive invalid within an INCLUDE file. An END directive is 
present within an INCLUDE file. See the Assembler Directives section in this manual for 



infnrmatinn nn IMP! i iHP fiioc 



***** ERROR 016: ENDR or ENDIF mis- matched. An incorrect termination directive is 
used on a conditional assembly block. This error may occur if an ENDR is used to terminate a 
IF block, if an ENDIF is used to terminate a REPEAT block, or if REPEAT and IF blocks overlap 
each other. 



***** ERROR 017: Iteration limit exceeded. An attempt has been made to assemble a 
REPEAT block more than the number of times specified in the second parameter of the 
REPEAT directive. If this parameter is not specified, the error message is displayed after 256 
repeat cycles are completed. 



***** ERROR 018: Misplaced ELSE. Either an ELSE directive is outside an IF-ENDIF block, 
or more than one ELSE directive is within an IF-ENDIF block. 



***** ERROR 019: Operation invalid for address. An operation requiring scalar operands 
has been applied to an address value. 



***** ERROR 020: Divisor is zero. A division or a MOD operation attempted to use zero as 
a divisor. 



*****ERROR 21: Text following "]" ignored. The information following a bracketed macro 
parameter has been ignored. For example, [BC]DE results in a parameter of BC (and 
generates this error message). Refer to the Macro section of this manual for further 
information on parameters. 



***** ERROR 022: ENDOF operand is scalar. The specified parameter of an ENDOF 
function is a scalar or non-global symbol. 
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ENDOF function upon an address resulting from a previous ENDOF function. 
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***** ERROR 024: ENDOF operand is not global. The specified parameter of an ENDOF 
function is a scalar or non-global symbol. 



***** ERROR 025: Operation on HI or LO of address. An attempt has been made to add or 
subtract the result of a HI or LO function. 



***** ERROR 026: Addition of addresses. An attempt has been made to add two 
addresses. 



***** ERROR 027: Conflicting section bases. An attempt has been made to subtract or 
compare addresses based on different sections. 



***** ERROR 028: Address subtracted from scalar. An attempt has been made to subtract 
an address from a scalar value. 



***** ERROR 029: Negative string length. A declaration in the STRING directive specifies 
a maximum length that is either negative or greater than 32767. 



***** ERROR 030: String length phase error. The declared length in the STRING directive 
differs between the first and second assembler passes. This error may be caused by a SET 
directive with a forward reference. 



***** ERROR 031: Redeclaration of string variable. An attempt has been made to 
redeclare a string variable. This error may occur if a STRING directive is inside a REPEAT 
loop or inside a macro which is expanded more than once. 



***** ERROR 032: String declaration phase error. A string value has been defined during 
the second assembler pass but not during the first pass. This error may be caused by a SET 
directive with a forward reference. 
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***** ERROR 033: Invalid string name. An invalid symbol is used as a string variable name 
in a STRING directive. See the Assembler Directives section for more information on the 



.^TRIMfn Hi motive 



***** ERROR 034: END inside an unclosed block. An END statement occurs within an IF 
block, a REPEAT block, or a MACRO definition block. This error may occur if the ENDM, 
ENDR, or ENDiF directives are either missing or misspelled. 



***** ERROR 035: Value truncated to byte. The value entered exceeds one byte (allowable 
range -128 to +255). The value is truncated to fall within this range. 



***** ERROR 036: Invalid character follows label. A label has not been followed by a 
space or tab character. 



***** ERROR 037: Extra operands ignored. One or more extra operands appear in a 
statement. The statement is assembled and the extra operands are ignored. This error may 
occur if a statement is miscoded, if an invalid delimiter is used for an operand list, or if a 
semicolon does not precede a comment. This error may also occur if an invalid character 
occurs within a symbol (for example, AB%C). 



***** ERROR 038: String variable used as label. A string variable is present in the label 
field of a statement other than a SET directive. The label field is ignored. 



***** ERROR 039: Invalid operation code. The assembler is unable to recognize or process 
a symbol or character in the operation field of a statement. This error may occur if an 
operation is misspelled, if a macro invocation precedes its definition, or if an invalid delimiter 
follows a label. 



***** ERROR 040: Invalid character. A character not in the assembler character set has 
been used outside of double quotes. Refer to the "Source Module Character Set" in the 
Tables section of this manual. 



***** ERROR 041: Syntax error. A statement does not conform to the required syntax. 
Refer to the Language Elements section of this manual for the correct syntax. 
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***** ERROR 042: Invalid option or separator. An invalid delimiter has been used between 
listing control options in the LIST or NOLIST directive operand field. Spaces are not valid 
delimiters. This error may occur if spaces are used in place of commas to delimit the options, 
or if an invalid listing control option is used. 



***** ERROR 043: No label on EQU or SET. An EQU or SET directive has a missing or 
invalid label field. 



***** ERROR 044: Invalid macro name. A macro name is missing or invalid. The macro 
body is ignored. This error may occur if the macro name is already defined or if an invalid 
delimiter is used before the macro name. 



***** ERROR 045: Invalid relocation option. An invalid relocation option has been used in 
a section directive. (Valid options are: PAGE, INPAGE, and ABSOLUTE.) The assembler 
ignores the invalid option and assumes the section to be byte-relocatable. This error may 
occur if the option is misspelled or is not preceded by a comma. 



***** ERROR 046: MACRO within a macro. A MACRO directive occurs within a macro 
definition block. The MACRO directive is ignored. 



***** ERROR 047: Invalid except in Macro. An EXITM, ENDM, REPEAT, or ENDR directive 
appears outside of a macro definition block. 



***** ERROR 048: Invalid operand. The specified operand is either incomplete or 
inaccurate for the BYTE, WORD, ASCII, BLOCK, ORG, or TITLE directives. 



***** ERROR 049: Address assigned to string. An attempt has been made to assign an 
address value to a string variable. 



***** ERROR 050: Section definition Phase error. The specified section relocation option 
differs between pass 1 and pass 2. This error may occur if a SET directive has a forward 
reference. 



13-6 (ffi 



Error Messages — 8002A: Assembler Users Manual 



***** ERROR 051: Section definition Phase error. The specified section is defined during 
the second, but not the first, pass of the assembler. This error may occur if a SET directive 
has a forward reference. 



***** ERROR 052: Too many Sections or Globals. The number of declared sections and 
other global symbols exceeds 254 during the processing of a SECTION directive. The current 
section declaration is not accepted by the assembler. 



***** ERROR 053: Invalid relocation option. An ABSOLUTE relocation option has been 
specified within a RESERVE directive operand field. 



***** ERROR 054: Negative RESERVE length. The RESERVE operand is either negative or 
greater than 32767. 



***** ERROR 055: Invalid section name. An invalid symbol has been declared as a 
SECTION, COMMON, or RESERVE name. This error may occur if a section name is 
misspelled, contains invalid characters, or is a previously defined label or reserved word. 



***** ERROR 056: Invalid RESERVE length. The required RESERVE expression is either 
specified incorrectly, specified without a comma before the expression, or missing from the 
RESERVE directive. 



***** ERROR 057: RESUME section undefined. The resumed section has not been 
previously defined with a SECTION or COMMON directive. This error may occur if the 
parameters of the SECTION or COMMON directives are misspelled or use invalid characters. 



***** ERROR 058: RESUME of RESERVE section. A RESUME directive has been used 
with a RESERVE section name. 



***** ERROR 059: Resumed section invalid. A resumed section has been defined after the 
number of declared sections and other global symbols exceeded 254. The section being 
resumed is discarded. 
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***** ERROR 060: Global operand already defined. A global symbol has been defined 
more than once. See the GLOBAL directive in the Assembly Directives section for correct 



usage of global symbols. 



***** ERROR 061: GLOBAL declaration Phase error. A global symbol has been used 
before it is defined. This message may be caused by a SET directive with a forward reference. 



***** ERROR 062: Too many Sections and Globals. The number of declared sections and 
other global symbols exceeded 254 during the processing of a GLOBAL directive. The current 
global declaration is not accepted by the assembler. 



***** ERROR 063: Invalid radix. An invalid radix follows a constant. The assembler 
recognizes hexadecimal (H), octal (0 or Q), and binary (B) constants, and defaults to decimal 
when no radix is specified. 



***** ERROR 064: Invalid digit. An invalid digit is associated with a specified radix. For 
example, the binary number 10031 B contains an invalid digit (3). 



***** ERROR 065: Unmatched string or parameter delimiter. An opening quotation mark 
or bracket is not matched by a closing quotation mark or bracket. 



***** ERROR 066: Line too long after replacement. The expanded line (containing single 
quotes used as replacement indicators) is too long. Only 127 characters are allowed. 



***** ERROR 067: Extra replacement identifier. One or more characters follow the 
replacement identifier (an item enclosed in single quotes) within a macro definition block. For 
example, '#bug' generates this error. 



***** ERROR 068: Replacement invalid outside of macro. Replacement identifiers (# and 
@) are used outside of a macro definition block. 
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defined as a string. 



***** ERROR 070: Invalid replacement identifier. An invalid symbol or symbols have been 
used for the replacement specification. For example, '???' is invalid. 



***** ERROR 071: Scalar value required. An address value has been used where a scalar 
is required. 



***** ERROR 072: Invalid expression. The expression is either invalid or incomplete for the 
specified operation. 



***** ERROR 073: Section size Phase error. The number of bytes generated for this 
section during the first pass is not the same as the number of bytes generated during the 
second pass. This error may occur if a SET directive is used with a forward reference. 



***** ERROR 074: Undefined symbol. No value has yet been assigned to a symbol used in 
an expression. 



***** ERROR 075: String truncated. More characters are assigned to a string than allowed 
by its definition. 



***** ERROR 076: Negative SEG operand. The parameter of the SEG function is either 
negative or greater than 32767. 



***** ERROR 077: SEG starting operand is zero. The starting position parameter of the 
SEG function is zero. 



***** ERROR 078: Insufficient workspace. An internal work area of the assembler is full. 

TU:— ~-.-~.. „.-,.. „„„..- \t r* + r'.nr* f . . —. n* I .-. r-. r« r^r nnri/Jiti/MIO i OCCOmMll InOilQ I r"»0 1 lffi^> ■ QI->+ mpmnril trt 

I I lid CI I UI lliay UV/I/UI ll Oil 11 ly lUliouuiis \j\ \*.vji iuiliui idi abaci nuiy 10a v& iiisuiin/n/in "iCmwi y i" 

perform the required functions. 
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ERROR 079: Value too large. The operand of the SPACE directive exceeds 255. 



***** ERROR 080: Invalid NAME symbol. The NAME symbol is invalid because it does not 
begin with a letter. 



***** ERROR 081: Illegally substituted ENDM. An ENDM directive within a macro 
expansion precedes the normal macro ending. 



***** ERROR 082: Nested INCLUDE directive. The source code inserted into the program 
with an INCLUDE directive contains another INCLUDE directive. See the Assembler 
Directives section for information on the INCLUDE directive. 



***** ERROR 083: Missing ENDIF. The ENDIF directive is missing from a conditional IF 
block. 



***** ERROR 084: Missing ENDM for included macro. The ENDM directive is missing 
from a macro definition block. 



***** ERROR 085: String value too large. The length of a string used as a number exceeds 
two characters. 



***** ERROR 086: Shift count exceeds 1 6. An attempt has been made (using SHL or SHR) 
to shift more than 16 bit positions in one operation. 



***** ERROR 087: Too many symbols. The assembler symbol table is filled. This is a fatal 
error; assembly is aborted. This error occurs when too many symbols have been used. The 
source module must be divided into smaller pieces to permit assembly. 



***** ERROR 088: Invalid transfer label. The label used for a transfer address on an END 
directive is not an address defined in the current source module. 



13-10 (® 



Error Messages— 8002A: Assembler Users Manual 



***** 
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been used with a bound global instead of a section. 



***** ERROR 091: Unable to assign INCLUDE file. TEKDOS is unable to access an 
INCLUDE file. This occurs when an illegal file or device is specified. (For example, INCLUDE 
"LPT1" specifies a reserved device.) This error message is preceded by an SRB status code 
indicating the reason that the specified file cannot be accessed. Refer to the Error Codes 
section of the 8002A System User's Manual for individual descriptions of the SRB status 
codes. 



***** ERROR 092: Illegal operation on a global. An attempt has been made to assign a 
value to a global symbol with the SET directive. 
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Section 14 
GLOSSARY 



Absolute. Having a specified location in memory: not relocatable. An absolute address 
specifies the actual location of a byte in memory. 

Actual Parameter. See Parameter. 

Address. A number or symbol that specifies a byte in memory. A 16-bit address has a value 
in the range to 65535 (FFFF hexadecimal). 

Assembler. The TEKDOS program that translates assembly language programs into machine 
language. 

Assembly Language. A microprocessor-specific programming language that allows the 
symbolic representation of any processor operation. Each operation is coded as one assembly 
language statement. 

Base. The base of a section of object code is the location of the first byte in the section. 

Binary. The base 2 numbering system. A binary digit, or bit, has the value or 1 . A binary 
constant in an assembly language program requires the suffix B. For example, the decimal 
number 29 may be written as 11101B. 

Bound Global. See Global. 

Byte-Relocatable. See Relocatable. 

Carriage Return. See Return. 

Code. To translate a sequence of operations into a series of statements in a programming 
language. The statements of a program are called source code. The machine instructions 
produced by assembling source code are called object code. 
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Command File. A disc file containing commands to be processed byTEKDOS or by a system 
program such as the linker or library generator. 



Command File Invocation. A method of invoking the linker or library generator. 

LINK @comfile or LIGBEN @comfile 

invokes the linker or library generator and specifies that commands are to be read from the 
designated command file rather than from the system terminal. 



Comment. A source program line, or part of a line, that is ignored by the assembler. 
Comments are used for program documentation. A semicolon (;) signifies that the rest of the 
line is a comment. 



Common. A section of memory that may be shared by any number of subprograms. The 
assembler directive COMMON declares a common section. The linker assigns the same area 
of memory to all common sections with the same name. 



Concatenation. Connecting end-to-end. For example, the concatenation "FLIP":"FLOP" 
yields the string "FLIPFLOP". The colon (:) is the concatenation operator used in assembly 
language programs. 



Conditional Assembly. A feature of the Tektronix Assembler that allows a block of source 
code to be assembled many times or not at all, depending on conditions defined earlier in the 
source module. 



Constant. A value expressed in literal form rather than as a symbol. A numeric constant is 
written as a string of digits, optionally followed by a letter that indicates the radix (for 
example, 29, 1 1 101 B, 350, 1 DH). A string constant is written as a character string in quotes 
(for example, "TEXT", "P.O. Box 500", ""). 



Converter. A system program that translates an assembly language program written for 
another assembler into a format suitable for processing by the Tektronix Assembler. 



Data Item. A byte or sequence of bytes of object code that contains data other than machine 
instructions. A data item is defined by an ASCII, BLOCK, BYTE, or WORD directive. 
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Default. A predefined value for a parameter, used when no value for the parameter is 
explicitly specified. 



Defined Symbol. A symbol that has been assigned a value. 



Directive. An assembly language statement that does not represent a machine instruction 
but does provide special information to the assembler. Also called a pseudo-operation, 
pseudo-instruction, or quasi-instruction. 



End Address. The address of the last byte in a section. 



Expression. A formula that contains symbols, constants, or functions related by operators, 
and yields a numeric or string value when evaluated. Symbols, constants, and functions are 
themselves trivial expressions. 



Formal Parameter. See Parameter. 



Forward Reference. Use of a symbol that is not defined until later in the current source 
module. 



Function, Assembler. A predefined function that may be used in assembly language 
expressions. An assembler function has the form func(expr), where func is the name of the 
function and expr is one or more expressions separated by commas. 



Global (or Global Symbol). A symbol that is assigned a value in one module and referred to 
in another. A bound global is defined in the current module. An unbound global is undefined 
in the current module; its value must be supplied by another module or by the linker 
command DEFINE. 
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Hexadecimal. The base 16 numbering system. Hexadecimal digits include the digits 
through 9, and the letters A through F to represent the decimal values 10 through 15. A 
hexadecimal constant in an assembly language program requires the suffix H and begins 
with a decimal digit to distinguish it from a symbol. For example, the decimal number 29 may 
be written as 1DH. The decimal number 15 may be written as OFH (but not FH). 



Inpage-Relocatable. See Relocatable. 



Instruction. A machine instruction is a sequence of bytes that directs a microprocessor to 
perform an elementary operation such as load, store, add, or branch. An assembly language 
instruction is an alphanumeric representation of a machine instruction. The assembler 
translates an assembly language instruction into the corresponding machine instruction. 



Interactive Invocation. A method of invoking the linker or library generator. When you enter 
the LINK command without parameters, or the LIBGEN command without specifying a 
command file, you must enter further linker or library generator commands from the system 
terminal. 



Label. A symbol that represents an address, variable, or constant in an assembly language 
program. 



Library. A collection of object modules that usually contains commonly-used subroutines. 
You may include calls to library routines in your source program; the linker includes the 
necessary object modules in the load file. 



Library Generator (LibGen). The TEKDOS program used to create and maintain libraries of 
object modules. 



Linker. The TEKDOS program that combines object modules into a single executable load 
file. 



Listing. A file or printout that summarizes the actions of a program such as the assembler, 
linker, or library generator. 
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Local. Not global in an assembly ianguage program, a iocal symbol is referenced only by 
statements in the same source module. 



Location Counter. An internal counter maintained by the assembler that marks the location, 
relative to the beginning of the section, of the next machine instruction to be assembled. A 
symbol in the label field of an assembly language statement is usually assigned the current 
value of the location counter. 



Machine Instruction. See Instruction. 



Machine Language. The binary language of a microprocessor. A high-level or assembly 
language program must be translated into machine instructions before the microprocessor 
can execute the program. Relocatable machine language produced by the assembler may 
require adjustment by the linker in order for the instructions to execute properly. 



Macro. A frequently-used group of assembler statements that are inserted into the program 
at assembly time wherever the macro is invoked. 



Macro Definition. A group of assembler statements that define a macro. A macro definition 
begins with a MACRO directive and ends with an ENDM directive. Statements in the macro 
definition may contain formal parameters, which are replaced with actual parameters 
wherever the macro is invoked. 



Macro Expansion. The process of replacing a macro invocation with the macro definition 
block it invokes. 



Macro Invocation. An assembler statement containing the name of a macro in the operation 
field and, optionally, a list of actual parameters in the operand field. 



Mnemonic. A symbol that represents a machine instruction. Usually the symbol is an 
abbreviation that suggests the machine operation to be performed. For example, the 8080A 
mnemonic MOV represents a machine instruction that moves a vaiue into a register. 
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Module. A program unit that is complete for purposes of assembling, linking, or loading. It 
may be combined with other modules to produce a complete program. An object module 
contains all the object code produced in a single assembler run. A source module is a set of 
assembly language statements (ending with an END directive or an end-of-file) that produces 
an object module when assembled. 



Nest. (1) To include a block of assembly language statements inside another block of 
statements of the same type. (2) To include a subexpression within an expression. 



Null String. An empty character string without quotes: nothing. 



Object Code. Machine language produced by the assembler from source statements. An 
object module contains one or more sections of object code, plus special information used 
by the linker, library generator, or LOAD command. An object file is a disc file that contains 
an object module. 



Octal. The base 8 numbering system. The eight octal digits are through 7. An octal 
constant in an assembly language program requires the suffix letter or Q. For example, the 
decimal number 29 may be written as 350 or 35Q. 



Operand. A number or other value on which an operation is performed. The expression X + 3 
performs an add operation on the operands X and 3. The assembly language statement LDA 
NUM1 performs a load operation on the byte addressed by the operand NUM1. 



Operator. A character or symbol that represents an operation to be performed on one or 
more operands. Operators used in assembly language programs are: 

* / + - MOD (arithmetic) 

\ & ! !! SHL SHR (bit manipulation) 

= <<=>>=<> (relational) 

(string concatenation) 

Page. A subdivision of memory. Page size is processor-dependent and reflects addressing 
considerations. For example, in a 64K memory with 256-byte pages, the high-order byte of a 
16-bit address selects one of the 256 pages and the low-order byte of the address selects a 
byte within that page. 
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Page-Relocatable. See Relocatable. 



Parameter. In a TEKDOS command, a parameter is a name or number that follows the 
command word and tells something about how the command is to be executed. 
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invoked. A formal parameter is a place holder in a macro definition block; the first formal 
parameter is written as '1 ', the second as '2', and so on. An actual parameter is a character 
string in a macro invocation that replaces each occurrence of the corresponding formal 
parameter in the macro biock. "Parameter" may refer to either a formal parameter or an 
actual parameter. 



Program Memory- The 8002A /^Processor Lab memory used as a substitute for prototype 
memory in the early stages of prototype development (emulation modes and 1). User 
programs run in program memory, as do the assembler, linker, library generator, and certain 
other system programs. 



Relocatable. A relocatable section is a section whose location in memory is not determined 
until link time. A page-relocatable section must begin on a page boundary; an inpage 
relocatable section may not cross page boundaries; a byte-relocatable section may be 
positioned anywhere in memory; an absolute section must start at a specified address. 



Reserved Word. A predefined symbol that has a special meaning to the assembler and may 
not be used as a label, section name, or module name. Reserved words include mnemonics, 
register names, and assembler directives and functions. 



Return. The RETURN character (ASCII code 13), also called CR or carriage return. This 
character marks the end of a command or an assembly language statement. 



Scalar. A 16-bit signed numeric value not used as an address. A scalar takes a value in the 
range -32768 to +32767. 



Section. A section of object code is a block of contiguous bytes, and is the fundamental, 
indivisible unit handled by the linker. A section of source code comprises the statements 
that will produce a section of object code when they are assembled. Each section of source 
code begins with a SECTION, COMMON, or RESERVE directive. 
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Simple Invocation. A method of invoking the linker in which all actions to be taken by the 
linker are specified in the LINK command line. 



Source Code. Program statements written in assembly language. A source module is a set 
of source statements (ending with an END directive or an end-of-file) that produces an object 
module when assembled. A source file is a disc file containing all or part of a source module. 



Start Address. The address of the base, or first byte, of a section. 



String. A sequence of ASCII characters. A string enclosed in quotes (for example, 
"ELEPHANT") is called a string constant. 



Symbol. A string of one to eight characters beginning with a letter and containing only 
letters, digits, periods, underscores, or dollar signs. Predefined symbols include assembler 
directives and functions, mnemonics, and register names. User-defined symbols represent 
addresses, data items, variables, macros, sections, or modules. 



TEKDOS. Tektronix Disc Operating System; the operating system of the 8002A //Processor 
Lab. 



Transfer Address. The address of the first machine instruction to be executed in a load file. 
A transfer address may be specified in the END statement of a source module or in the linker 
command TRANSFER. 



Unbound Global. See Global. 



Variable. In an assembly language program, a value that may be altered during assembly. 
The SET directive creates or redefines a variable. 
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INDEX 



Absolute, defined, 14-1 

Absolute (relocation type), 2-8, 5-6, 5-40 

Actual parameter, defined, 14-7 

Address, defined, 14-1 

Address values, 4-8, 4-18 

Addressing modes, section 1 2 

AFTER (LibGen parameter), 8-14 

Allocation of sections, 7-6 

Arithmetic operators, 4-14 

ASCII codes (hexadecimal), table of, 10-5 

ASCII directive, 5-3 

sample usage, 3-17 

ASM command, 3-3 

Assembler: 

demonstration, 1-13, 1-19 

execution, 3-5 

features, 1-4 

input, 3-4 

invoking the, 2-4, 3-3 

macro. See Macro 

variable, 4-9 

Assembler directives, section 5 
defined, 4-3, 14-3 
labels for, 5-2 
list of, 10-3 

Assembler listing: 

explanation of, 3-6 
example, 1-20, 3-8 
headings, 5-46, 5-49 
options, 5-23 
statistics, 3-7, 3-18 

Assembler specifics, explanation, 1-2, section 12 

Assembly: 

combining source files during, 2-2 
conditional: 

blocks, 3-13, 5-19, 5-34 

defined, 14-2 

example of, 9 : 38 

Assembly language, defined, 14-1 

Assembly language instructions: 
defined, 4-3, 14-4 
notational conventions for, section 1 2 

B 

BASE: 

assembler function, 4-20 
linker option, 7-21 

Base, defined, 14-1 

BEFORE (LibGen parameter), 8-14 

Binary, defined, 14-1 

Bit, defined, 14-1 

BLOCK directive, 5-4 
sample usage, 3-15 



Bound global: 

description, 5-17 
defined, 14-3 

Byte-relocatable, defined, 14-7 

"Bytes available" message, 1-14, 3-7 



Characters, special: 
@ (at sign): 

LibGen command, 8-10 

linker command, 7-15 

macro construct, 6-4, 9-41 

using the, 9-41 
$ (dollar sign), 4-8 
% (percent sign), 4-1 1, 6-5 
# (pound sign), 6-4 
A (up arrow), 6-5 
disabling significance of, 6-5 

CND (listing option), 5-24 

Code, defined, 14-1 

Command file, defined, 4-2, 14-2 

Command file invocation: 
defined, 14-2 
LibGen, 8-1, 8-4, 8-10 
linker, 7-1, 7-15 

Command name, 3-2 

Comment, defined, 14-2 

Comment field, 4-5 

COMMON directive, 5-6 
sample usage, 3-15 

Common section, 5-6 

CON (listing option), 5-25 

Concatenation: 
defined, 14-2 
string, 4-19 

Conditional assembly. See Assembly, conditional 

Constant: 

defined, 14-2 
numeric, 4-8, 14-2 
string, 4-9, 14-2 

Constant values, example of creating, 9-32 

Converter, defined, 14-2 

<CR> (carriage return), 1-6 
defined, 14-7 



Data item, defined, 14-2 
DBG (listing option), 5-25 
Decimal-hexadecimal-binary equivalents, table of, 

10-6 
DEF function, 4-22 
Default, defined, 14-3 
Default section, 3-18, 5-41 
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DEFINE (linker command), 7-16 
DELETE (LibGen command), 8-1 1 
Demonstration run, 1-6 
Directive, defined, 14-3 



Editor demonstration, 1-11 

ELSE directive, 5-10 

END: 

directive, 5-11 

LibGen command, 8-12 

linker command, 7-17 

End address, defined, 14-3 

ENDIF directive, 5-12 

ENDM directive, 5-13, 6-2, 6-6 

ENDOF function, 4-23 

ENDR directive, 5-14 

ENDREL, 7-7 

Entry point, 5-17 

EQU directive, 5-15 

sample usage, 3-14 

Error messages: 

assembler, 1-14 
LibGen, 8-7 
linker, 7-11, 7-27 
processor-specific, section 1 2 
user-defined, 5-50 
sample usage, 3-13 

Errors, assembler, 3-7 
example of, 3-14, 

Executable object code, 1 -25 

Execution, assembler, 3-5 

EXITM directive, 5-16 

Expression, 4-12, 14-3 

EXTRACT LibGen command, 8-13 



Field: 

comment, 4-5 
defined, 1-8, 4-4 
label, 4-2 
operand, 4-4 
operation, 4-3 

File naming, 1-11 

Formal parameter, defined, 14-7 

Forward reference: 
defined, 14-3 
use of, 3-5 

Functions, assembler: 
defined, 14-3 
description, 4-19 
table of, 4-12 



Global: 

bound, 5-17 
defined, 14-3 
example of, 5-18 
unbound, 5-17 

GLOBAL directive, 5-17 
sample usage, 3-14 

Global symbols list, 7-9 
example of, 1-24 



H 

Hexadecimal, defined, 14-3 
Hexadecimal addition, table of, 10-7 
Hexadecimal multiplication, table of, 10- 
Hl function, 4-24 

sample usage, 3-13 

I 

IF directive, 5-19 

IF.. ELSE. ..ENDIF block, 5-19 

IF. .ENDIF block, 5-19 
sample usage, 3-13 

INCLUDE directive: 
description, 5-22 
using the, 9-42 

INPAGE: 

linker option, 7-21 

relocation type, 5-6, 5-37, 5-40 

Input, assembler, 3-4 

INSERT (LibGen command), 8-14 

Instruction set, processor, section 12 

Interactive invocation: 
defined, 14-4 
LibGen, 8-1,8-2 
linker, 7-1, 7-3 

Internal symbol list, 5-25, 7-9 



Label field, 4-2 

Label generation, unique ('@') f 6-4 

Labels for assembler directives, 5-2 

LibGen: 

command entry, terminating, 8-12 

command file, invoking a, 8-4, 8-10 

commands, use of, 8-9 

error messages, 8-7 

execution of, 8-5 

features, 1-5 

interactive commands: 

@, 8-10 

DELETE, 8-11 

END, 8-12 

EXTRACT, 8-13 

INSERT, 8-14 

LIST, 8-16 

LOG, 8-17 

NEVVLIB, 8-18 

NOLOG, 8-19 

OLDLIB, 8-20 

REPLACE, 8-21 
invocation: 

command file, 8-4, 8-10 

interactive. 8-1, 8-2 
library file, 8-5 
listing, 8-5 
output, 8-5 
using, 2-10 

Libraries, combining, 2-14 

Library: 

building a, 2-10 

creating a user-defined, 2-11 

defined, 14-4 

Library file: 

as LibGen output, 8-6 
linking a, 7-7 
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Library generator. See LibGen 

Library module: 

Suuincj a new, «t- 1 ^. 
deleting a, 8-11 
extracting a, 2-13, 8-13 
replacing a, 2-13, 

LINK (linker command), 7-18 

LINK (TEKDOS command), 7-1 

Linker: 

command processing errors, 7-27 
commands, use of, 7-14 
demonstration, 1 -22 
error messages, 7-1 1 
execution, 7-5 
features, 1-5 
interactive commands: 

@, 7-15 

DEFINE, 7-16 

END, 7-17 

LINK, 7-18 

LIST, 7-19 

LOAD, 7-20 

LOCATE, 7-21 

LOG, 7-22, 7-24 

MAP, 7-23 

NOLOG, 7-24 

NOMAP, 7-23, 7-25 

TRANSFER, 7-26 
invocation: 

command file, 7-1, 7-4 

interactive, 2-5, 7-1, 7-3 

simple, 2-4, 7-1, 7-2 
listing file, 7-8 
maps, 7-10 

memory, 1-30, 7-10 

module, 1-31, 7-10 
output, 7-8 
statistics, 7-1 1 

Linker listing: 

displaying internal symbols in the, 2-3 
example of, 1-23 

Linking a program, 2-4 

Linking to a library file, 7-7 

Linking to an address range, 2-7 

LIST: 

directive, 5-23 

sample usage, 3-12 
LibGen command, 8-16 
linker command, 7-19 

Listing: 

assembler: 

example of, 3-8 

explanation of, 3-6 
headings for assembler, 5-46, 5-49 
LibGen, 8-6 
linker, 1-23 
source, 3-6 
See also Assembler listing 

LO function, 4-25 

LOAD: 

linker command, 7-20 
TEKDOS command, 1-25 

Local, defined, 14-5 

LOCATE (linker command), 7-21 

Location counter: 
defined, 14-4 
described, 4-8 
setting the, 5-30 



LOG: 

LibGen command, 8-17 
linker command, 7-22, 7-24 

Logical operators, 4-16 

M 

Machine instruction, defined, 14-4 

Machine language, defined, 14-5 

Macro: 

assembly of, 3-5 

body, 6-3 

defined, 6-1, 14-5 

examples of, 3-13, 6-11, 9-2, 9-27 

expansion: 

defined, 6-2, 14-5 

display of statements in, 5-24 
invocation, defined, 4-4, 6-2, 6-6, 14-5 
operators, 6-3 
parameter: 

access, 6-4 

conventions, 6-6 

sample usage, 3-16 

MACRO directive, 5-27, 6-2 

Manual overview, 1-1, 1-27 

MAP (linker command), 7-23 

ME (listing option), 5-24 
sample usage, 3-17 

MEG (listing option), 5-24 

Memory, reserving an area of, 2-8, 5-4, 5-37 

Memory map: 

description, 7-10 
example of, 1 -24 

Memory-mapped I/O, 2-9 

Mnemonic, defined, 14-5 

Mnemonics, processor, section 12 

MOD operator, 4-14 

Module: 

defined, 14-6 
object, 3-6 

Module map: 

description, 7-10 
example of, 1-24 

N 

NAME directive, 5-28 

NCHR function, 4-26 

Nest, defined, 14-6 

Nesting conventions for assembly language 

statements, 5-20, 5-35 

NEWLIB (LibGen command), 8-18 

NOLiST directive, 5-29 

NOLOG: 

LibGen command, 8-19 
linker command, 7-24 

NOMAP (linker command), 7-23, 7-25 

•NONAME*, 5-28 
Null string, defined, 14-6 
Numeric values, 4-7 
Numeric variable, 4-9, 5-42 
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Object code: 

defined, 14-6 
example of, 3-8 
executable, 1-25 
relocatable, 1-25 

Object file, defined, 14-6 

Object module: 
defined, 14-6 
description of, 3-6 
name of, 5-28 

Octal, defined, 14-6 

OLDLIB (LibGen command), 8-20 

Operand: 

defined, 14-6 
use of, 4-4 

Operand field, 4-4 

Operation field, 4-3 

Operators: 

arithmetic, 4-14 
defined, 4-13, 14-6 
hierarchy of, 4-13 
logical, 4-16 
relational, 4-17 
string, 4-19 
table of, 4-12 

ORG directive, 5-30 

Overview of manual, 1-1,1 -27 

Overview of programming process, 1-2 



PAGE: 

directive, 5-33 

linker option, 7-21 

relocation type, 5-6, 5-37, 5-40 

Page (of memory), defined, 14-6 

Page size, processor, section 1 2 

Page-relocatable, defined, 14-7 

Parameter, defined, 3-2, 14-7 

Parameter count (macro), 6-4 

Passes, assembler, 3-5 

Procedures, 2-1 

Program memory, defined, 14-7 

Program modules, example of, 1-8 

Program section, 5-40 

Programming process: 
figure, 1-3 
overview of, 1 -2 



RANGE (linker option), 2-7, 7-21 

Register names, section 12 

Relational operators, 4-17 
comparison table, 4-8 

Relocatable, defined, 14-7 

Relocatable address, 4-8 

Relocatable object code, 1 -25 

Relocation indicator, 3-6 
example of, 3-14 

Relocation of sections, example of, 5-31 



REPEAT directive, 5-34 
REPEAT.. .ENDR block, 5-34 
REPLACE (LibGen command), 8-21 
RESERVE directive, 5-37 
Reserve section, 5-37, 7-5 
Reserved words, section 12, 14-7 
RESUME directive, 5-39 
Return character, 14-7 



Scalar, defined, 14-7 

SCALAR function, 4-27 

Scalar values, 4-7, 4-17 

Section: 

allocation of, 7-6 
attributes, 7-5 
defined, 14-7 
examples of, 1-9, 5-32 

SECTION directive, 5-40 
sample usage, 3-14 

Section name, determining current, 6-5 

SEG function, 4-28 

Semicolon (comment), 4-5 
sample usage, 3-12 

Service call (SVC) generation, example of, 9-27 

Service request blocks, example of creating, 9-27 

SET directive, 4-10, 4-1 1, 5-42 
sample usage, 3-12 

SHL (shift left) function, 4-15 

SHR (shift right) function, 4-15 

Simple invocation, defined, 14-8 

Source code, defined, 14-8 

Source file, alternate, 5-22 

Source file, defined, 14-8 

Source listing: 

description, 3-6 

display of statements in, 5-24 

example of, 1-17, 3-8 

Source module, defined, 14-6 

Source module character set, 10-1 

Source program, example of, 3-1 1 

SPACE directive, 5-45 

Stack, allocating memory for, 5-38 

Start address, defined, 14-8 

Statement fields, 1-8, 4-1 

Statement types, 1 -8 

Statements, 4-1 

STITLE directive, 5-46 

String, defined, 14-8 

String constant, 4-9 

String conversions, 4-12 

STRING directive, 4-10, 5-48 
sample usage, 3-12 
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STRING function, 4-29 

String operator, 4-21 

String vaiues, 4-9, 4-18 

String variable, 3-12, 4-10, 4-11, 5-42, 5-48 
sample usage, 3-12 

Subroutine library, example of creating and using 

a, 9-6 

Summary of action. See LibGen listing 

SVC generation, example of, 9-27 

SYM (listing option), 5-25 

Symbol: 

assigning value to, 4-6, 5-2, 5-15, 5-42 

defined, 14-8 

description, 4-6 

predefined, 4-7 

undefined, example of, 3-18 

user-defined, 4-2, 4-6 

Symbol list. See LibGen listing 

Symbol table: 

description, 3-7 
controlling display of, 5-25 
example of, 1-17, 3-10 

Syntax notation, 3-1 

for assembler directives, 5-1 

System overview, 1-1 



TEKDOS, defined, 14-8 
TEKDOS SVC generation, example of, 9-27 
Terminating LibGen command entry, 8-14 
Text substitution, 3-5, 4-5, 4-13, 5-43 
Text substitution indicator, 3-5 
example of, 3-16 



niLt airective, o-^a 
sample usage, 3-12 

TRANSFER (linker command), 7-26 

Transfer address, defined, 5-1 1, 14-8 

TRM (listing option), 5-25 
sample usage, 3-12 

Two passes of the assembler, 3-5 

Type conversion, 5-42 

U 

Unbound global, defined, 5-17, 14-3 
Underlined characters in examples, 1-6 
Unique label generation, 6-4 
User-defined error messages, 5-50 



Variable: 

defined, 5-42, 14-8 
numeric, 4-9, 5-42 
string, 4-10, 5-42, 5-48 
sample usage, 3-12 

W 

WARNING directive, 5-50 
sample usage, 3-13 

WORD directive, 5-51 
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